Deployment and Development

After creating your own Hello World Extension with the help of the HiveMQ Extension Archetype you can implement custom logic based on your individual needs.
Check the Event Registry and Interceptors to find a list of events you can leverage.




Building HiveMQ Extensions

Building your HiveMQ Extension is as easy as executing the mvn: package goal when you have created your extension with the help of the HiveMQ Extension Archetype.
If this is not the case, you can extend your Maven packaging phase by following the steps described here.

Package Extension

This will build a file called <your-extension-version>-distribution.zip inside the target folder of your project.

Package Extension

Extending the packaging phase

A HiveMQ Extension needs beside a jar file also a hivemq-extension.xml. The mvn: package phase can be extended n order to create a complete extension withouth the need of manual steps.
This can be accomplished by following this steps:


  • Add a new property and build plugin to your pom.xml

<?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 name of the author which will be written into the hivemq-extension.xml.
2 The package phase is extended to create an extension with all needed files.
3 The assembly file which is used to create a fully working extension.


  • Create an assembly.xml file under the root path

<?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 an hivemq-extension.xml file under your resources folder

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




Deploying HiveMQ Extensions

Deploying your HiveMQ Extension to your HiveMQ instance is as easy as unzipping the <your-extension-version>-distribution.zip file and moving the included folder to the extensions folder of HiveMQ.

Install Extension

HiveMQ will automatically recognize the 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.
HiveMQ 4 and its Extension SDK support Extension Hot Reload. This means you can add and remove Extensions to HiveMQ during runtime.




Debugging HiveMQ Extensions with the Maven Plugin

An important part of any kind of software development, including the development of a custom HiveMQ extension, is the possibility of debugging the software.
This allows the developer to have an in-depth look into the behaviour of the software at runtime and provides a unique way of gaining insights, specifically when looking for causes of unwanted behaviour.
Regularly the debugging procedure demands that after every change an extension gets newly packaged, unzipped and deployed to the HiveMQ extensions folder (HIVEMQ_HOME/extensions) in order to initialize the extension on HiveMQ startup. This process is inconvenient and not suitable for a fast switching between developing and manual testing. Another set-back that an extension can not be debugged without a running HiveMQ instance. In order to overcome these mentioned setbacks for effective plugin development, we created the HiveMQ Maven Plugin to provide a more convenient way of debugging.

The Maven plugin helps developers to:

  • easily run their developed extension on HiveMQ for testing purposes

  • successfully debug their extension

Running your extension without debugging can be done by setting the debugMode to NONE. More configuration options can be found here.


The following shows how to debug a custom HiveMQ Extension, using two of the most commonly used Java IDE applications. IntelliJ and Eclipse.

In case you are using a different Java IDE, the general process described here does still apply.




Functionality

The Maven plugin automates the above stated steps, which are necessary to run an extension on a real HiveMQ instance. Therefore you need to have a HiveMQ instance located on your development machine, which the Maven plugin can use to deploy the extension under development to. When the Maven plugin is invoked it will create an ad-hoc extension directory in the maven build directory and will move the packaged extension files to the newly created folder.

Extensions folder of HiveMQ, when working with the Maven Plugin
The extensions folder of the HiveMQ instance, used from the Maven Plugin, is not used. Extensions or configuration files located there won’t be used when starting HiveMQ from within the Maven Plugin.

After preparing the extension the local HiveMQ in the specified directory will be started with the custom extensions folder. The Maven plugin will then show the HiveMQ console output. This provides an easy and powerful way for extension developers to test newly created extensions. Additionally it provides the capability to debug the extension during runtime using the Java remote application debugging mechanism. Java Remote Debugging is a client/server concept, in which both parties, application (HiveMQ with extension) and IDE, are able to be the server or the client. Each scenario has advantages and disadvantages:

  • HiveMQ with Extension: Server; IDE: Client

    • Advantage

      • Easier handling, because HiveMQ can be started without an IDE debugger being started first.

    • Disadvantage

      • If the code you want to debug is executed at startup, you have to be very quick in starting the IDE client debugger, otherwise the code you wish to debug is already been passed through.

  • HiveMQ with Extension: Client; IDE: Server

    • Advantage

      • It is possible to debug code at startup

    • Disadvantage

      • Before the HiveMQ can be started, your IDE’s debugging process needs to be up and running.

Both of these scenarios have appropriate uses and can be switch through the configuration options of the Maven plugin. It is also possible to specify the port on which they connect and the host name of the server, if HiveMQ is running in client mode.

This was just a quick overview over Java Remote Debugging in the context of HiveMQ extension development, for more insights see this link.


Usage

As an effective way to use the Maven plugin, a Maven profile attached to the Maven package goal has proven itself to be a great workflow. This triggers the extension to be ran on HiveMQ every time the Maven package goal is executed and the profile RunWithHiveMQ is active. In order to make it work as described the following changes has to be made.
This is already part of the project, if the provided HiveMQ Extension Archetype was used. In this case you simply need to provide the correct HiveMQ home folder in the configuration.

IDE Support
For more information on how to change the HiveMQ home folder with your favorite IDE look here.
Modify your pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    ...

    <profiles>
        <profile>
            <id>RunWithHiveMQ</id>
            <build>
                <plugins>
                    <plugin>
                        <groupId>com.hivemq</groupId>
                        <artifactId>hivemq-maven-plugin</artifactId>
                        <version>4.0.2</version>
                        <executions>
                            <execution>
                                <id>hivemq</id>
                                <phase>package</phase>
                                <goals>
                                    <goal>hivemq</goal>
                                </goals>
                                <configuration> (1)
                                    <hiveMQDir>
                                        /Applications/hivemq (2)
                                    </hiveMQDir>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
...
</project>
1 All configuration properties for the Maven plugin have to be placed in here.
2 Please specify the HiveMQ home directory. If you have not downloaded HiveMQ yet, please download the latest HiveMQ.


Configuration Options

In general, the Maven plugin has reasonable defaults, but sometimes it is necessary to adjust some settings or just to get an overview of the default settings.

The HiveMQ directory configuration property is the only mandatory one.
Table 1. Configuration Options
Name Default Required Description

hivemqDir

true

This need to be set to your local HiveMQ directory. If you have not downloaded HiveMQ yet, please download the latest HiveMQ.

hivemqJar

hivemq.jar

false

The name of the HiveMQ jar file in the bin directory.

extensionZipName

{artifactId}-{version}-distribution.zip

false

The Name of the extension zip file.

extensionDirectory

target

false

The directory in which your extension is located.

verbose

true

false

This property specifies, whether the messages logged from HiveMQ to the console should be shown or not.

noExtensions

false

false

When this is set to true, HiveMQ will start without using the extension, which is currently under development. A possible use case would be to compare the behaviour of HiveMQ with and without the extension.

debugMode

SERVER

false

Specifies the debug mode of the Maven plugin. Valid values are NONE, SERVER and CLIENT. Use NONE for starting HiveMQ + extension without debugging. When you want to debug the bootstrapping part of your extension use CLIENT, otherwise user SERVER. For more insights about debug modes see the functionality section. And make sure to configure your IDE corresponding to your debug mode.

debugPort

5005

false

The debug port on which the debug server starts when in SERVER mode or the client connects to when in CLIENT mode.

debugServerHostName

localhost

false

If the debugMode is CLIENT, through this property it is possible to specify the host name of the debug server (for example the machine your IDE is running on). This is only needed if you want to remotely debug your extension on another machine, see also the functionality section.

Debugging with IntelliJ

Server Mode

  • Set debugMode to SERVER, select profile RunWithHiveMQ and run Maven goal package

    IntelliJ debug mode SERVER 1

  • Create a new Remote Run Configuration

    IntelliJ debug mode SERVER 2

  • Make sure the Transport is set to Socket, Mode is set to Attach and the port is 5005.

    IntelliJ debug mode SERVER 3

  • Run the newly created Configuration

    IntelliJ debug mode SERVER 4


Client Mode

  • Set debugMode to CLIENT and create a new Run Configuration

    IntelliJ debug mode CLIENT 1

  • Select Remote Configuration

    IntelliJ debug mode CLIENT 2

  • Make sure the Transport is set to Socket, Mode is set to Listen and the port is 5005.

    IntelliJ debug mode CLIENT 3

  • Run the newly created Configuration

    IntelliJ debug mode CLIENT 4

  • Run Maven package and wait until HiveMQ is started

    IntelliJ debug mode CLIENT 5

  • Switch to the Debug window and check if it shows Connected

    IntelliJ debug mode CLIENT 6




Debugging with Eclipse

Maven Goal Package

  • Create new Run Configuration for Maven Goal

    Run Maven Package in Eclipse 1

  • Insert Maven Goal package und Profile RunWithHiveMQ

    Run Maven Package in Eclipse 2

  • Click apply and you are done!


Server Mode

  • Create new configuration element debugMode and set value to SERVER; Run Maven Goal package

    Debug Extension in Eclipse Server mode 1

  • Create a new Remote Java Application configuration

    Debug Extension in Eclipse Server mode 2

  • Make sure Connection Type is Socket Attach, the host is localhost, the port is 5005 and then click Debug

    Debug Extension in Eclipse Server mode 3

  • The debugger should be running now


Client Mode

  • Create a new Debug Configuration: Remote Java Application

    Debug Extension in Eclipse Client mode 1

  • Make sure Connection Type is Socket Listen, the port is 5005 and then click Debug

    Debug Extension in Eclipse Client mode 2

  • Change to the Debug Perspective and check if the debugger is listening

    Debug Extension in Eclipse Client mode 3

  • Create new configuration element debugMode and set value to CLIENT; Run the Maven Goal package

    Debug Extension in Eclipse Client mode 4

  • Start HiveMQ and wait until it is started.

    Debug Extension in Eclipse Client mode 5

  • Check if the debugger is connected

    Debug Extension in Eclipse Client mode 6