Deployment and Development

After you create your Hello World Extension Java project with the HiveMQ Extension Archetype, you can use the project as a basis to implement custom logic for your individual use case.
For a list of all the events you can leverage in your extension, see Event Registry and Interceptors.

Build Your HiveMQ Extension

If you created your extension with the HiveMQ Extension Archetype, you can simply execute the mvn: package goal to build your HiveMQ extension.

Package Extension

The package lifecycle builds an <your-extension-version>-distribution.zip file inside the target folder of your project.

Package Extension

If you used a different method to create your extension, follow the extend package phrase procedure to extend your Maven package.

Extend Packaging Phase

In addition to an extension .jar file, every HiveMQ extension requires a hivemq-extension.xml file.
To create a complete extension automatically, you can extend the mvn: package phase as follows:

Add a new property and build the Maven plugin to your pom.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    ...

    <properties>
        <author.name>
            Name of the Author (1)
        </author.name>
    </properties>
    <build>
        <plugins>
            <plugin>
                <artifactId>maven-assembly-plugin</artifactId>
                <executions>
                    <execution>
                        <id>assembly</id>
                        <phase>package</phase> (2)
                        <goals>
                            <goal>single</goal>
                        </goals>
                        <configuration>
                            <descriptors>
                                <descriptor>assembly.xml</descriptor> (3)
                            </descriptors>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
...
</project>

1	The author name that is written into the `hivemq-extension.xml`.
2	The package phase that is extended to create an extension with all necessary files.
3	The assembly file that is used to create a fully functional extension. Create an `assembly.xml` file in the root path of your project

<?xml version="1.0" encoding="UTF-8"?>
<assembly xmlns="http://maven.apache.org/xsd/assembly-1.1.2.xsd"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/xsd/assembly-1.1.2.xsd">
    <id>distribution</id>
    <formats>
        <format>zip</format>
    </formats>
    <files>
        <file>
            <source>src/main/resources/hivemq-extension.xml</source>
            <outputDirectory>/${artifactId}/</outputDirectory>
            <filtered>true</filtered>
        </file>
        <file>
            <source>target/${artifactId}-${version}.jar</source>
            <destName>${artifactId}-${version}.jar</destName>
            <outputDirectory>/${artifactId}/</outputDirectory>
        </file>
    </files>
    <includeBaseDirectory>false</includeBaseDirectory>
</assembly>

Create a hivemq-extension.xml file in your resources folder

<hivemq-extension>
    <id>${artifactId}</id>
    <name>${extension.name}</name>
    <version>${version}</version>
    <priority>1000</priority>
    <start-priority>1000</start-priority>
    <author>${author.name}</author>
</hivemq-extension>

Deploy Your HiveMQ Extension

To deploy your HiveMQ extension to your HiveMQ instance, unzip the <your-extension-version>-distribution.zip file and move the new extension folder to the extensions folder of your HiveMQ instance.

Install Extension

HiveMQ automatically recognizes and starts the extension:

HiveMQ Console

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

HiveMQ 4 and the HiveMQ extension framework support Extension Hot Reload. This feature allows you to add and remove extensions to HiveMQ during runtime.