Deployment and Development

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

Build 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.

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

Package Extension

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

Package Extension

Extend Packaging Phase

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

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 author name that is written into the hivemq-extension.xml.
2	The package phase that is extended to create an extension with all of the 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 installation.

Install Extension

HiveMQ automatically recognizes and starts 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 the HiveMQ extension framework support Extension Hot Reload. This feature allows you to add and remove extensions to HiveMQ during runtime.

Debugging HiveMQ Extensions with the Maven Plugin

Debugging is key to the development of your custom HiveMQ extension because it shows you exatly how your extension behaves at runtime. This in-depth view provides unique insights and makes it easier to quickly identify the cause of any unwanted behavior.

The usual debugging procedure packs, unzips, and deploys extensions after every change. This process is not suitable for quickly switching between development and testing. Additionally, the extension can not be debugged without a running HiveMQ instance.
To facilitate plugin development and provide a more convenient way to debug your extensions, HiveMQ created the Maven plugin.

Our Maven plugin provides the following advantages:

Easily run your extensions on HiveMQ for testing purposes
Efficiently debug your extension

If you want to run your extension without debugging, set the debugMode to NONE. More configuration options are available here.

The following information shows how to debug a custom HiveMQ extension with two of the most commonly used Java IDE applications (IntelliJ and Eclipse).

The process that we describe works with most Java IDE.

Functionality

The Maven plugin automates the steps that are required to run an extension on your HiveMQ instance. To deploy a new extension, your development machine must have a HiveMQ instance that the Maven plugin can use. When the Maven plugin is invoked, the plugin creates an ad-hoc extension directory in the Maven build directory and moves the packaged extension files to that folder.

The Maven plugin does not use the extensions folder of the HiveMQ instance. When you use the Maven plugin to start a HiveMQ instance, only the extensions folder in the Maven build directory is used.

After the Maven plugin prepares the extension, the local HiveMQ instance in the specified directory starts with the custom extensions folder. HiveMQ console output becomes visible in your selected IDE. This functionality provides an easy and powerful way for extension developers to test the newly-created extension. Additionally, you gain the ability to debug the extension during runtime with the Java remote-application debugging mechanism. Java remote debugging is a client/server concept in which the application (HiveMQ with extension) and IDE are able to be the server or the client. Each scenario has advantages and disadvantages:

HiveMQ with Extension as the Server and the IDE as 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 executes at startup, you must start the IDE client debugger very quickly to catch the code you want to debug before it passes through.
HiveMQ with Extension as the Client and the IDE as Server
- Advantage:
  - It is possible to debug code at startup.
- Disadvantage:
  - Before HiveMQ starts, the debugging process of your IDE must be up and running.

Both of these options have appropriate uses. You can switch scenarios as desired with the configuration options of the Maven plugin. When you run HiveMQ in client mode, it is also possible to specify the connection port and the host name of the server.

More information on Java remote debugging in the context of HiveMQ extension development is available here.

Usage

Use of a Maven profile attached to a Maven package goal is an effective way to use the Maven plugin. This workflow triggers the extension that you want to run on HiveMQ every time the Maven package goal is executed and the profile RunWithHiveMQ is active.
To use the workflow as described, you need to make the following changes.

If you created your project with the HiveMQ Extension Archetype, this workflow is aready part of your project. In this case, you simply need to provide the correct HiveMQ home folder in the configuration.

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 must be placed in here.
2	Specifies the HiveMQ home directory. If you have not yet downloaded HiveMQ, you can download the current version of HiveMQ here.

More information on how to change the HiveMQ home folder with your favorite IDE is available here.

Configuration Options

The HiveMQ Maven plugin uses sensible default settings. However, you can adjust many of the settings to suit your individual use case.

The hivemqDir property identifies your local HiveMQ directory. This property is mandatory and does not have a default setting.

Table 1. Configuration Options
Name	Default	Description
`hivemqDir`		The name of your local HiveMQ directory. If you have not yet downloaded HiveMQ, you can download the current version of HiveMQ here.
`hivemqJar`	hivemq.jar	The name of the HiveMQ jar file in the bin directory.
`extensionZipName`	{artifactId}-{version}-distribution.zip	The name of the extension zip file.
`extensionDirectory`	target	The directory in which your extension is located.
`verbose`	true	Defines whether the messages logged from HiveMQ are visible on the console. To view messages, set to true.
`noExtensions`	false	When this is set to true, HiveMQ starts without using the extension that is currently under development. You can use this setting to compare the behaviour of HiveMQ with and without the extension.
`debugMode`	SERVER	Specifies the debug mode of the Maven plugin. Possible values are NONE, SERVER and CLIENT. Use NONE to start HiveMQ and the extension without debugging. To debug the bootstrapping part of your extension use CLIENT. For other purposes, use SERVER. To learn more about debug modes, see the functionality section. Always make sure that the configuration of your IDE corresponds to your debug mode.
`debugPort`	5005	In SERVER mode, the debug port on which the debug server starts. In CLIENT mode, the debug port to which the client connects.
`debugServerHostName`	localhost	In CLIENT mode, this property can specify the host name of the debug server. For example, the machine on which your IDE runs). Use this property if you want to remotely debug your extension on another machine. For more information, see functionality.

Debugging with IntelliJ

Server Mode

Set the debugMode to SERVER, select the RunWithHiveMQ profile, and run the Maven goal package
Create a new Remote Run configuration
Make sure that the Transport is set to Socket, the Mode is set to Attach, and the port is 5005.
Run the newly-created configuration

Client Mode

Set the debugMode to CLIENT and create a new Run Configuration
Select Remote configuration
Make sure that the Transport is set to Socket, the Mode is set to Listen, and the port is 5005.
Run the newly-created configuration
Run the Maven package and wait until HiveMQ starts
Switch to the Debug window and verify that the status is Connected

Debugging with Eclipse

Maven Goal Package

Create a new Run Configuration for the Maven goal
Insert package as the Maven goal and RunWithHiveMQ as the profile
To complete the setup, select Apply

Server Mode

Create a new debugMode configuration element, set the value to SERVER, and run the package Maven goal
Create a new Remote Java Application configuration
Make sure the connection type is Socket Attach, the host is localhost, and the port is 5005. Click Debug
The debugger starts

Client Mode

Create a new Remote Java Application debug configuration
Make sure that the connection type is Socket Listen and the port is 5005. Click Debug
Change to the Debug Perspective and verify that the debugger is listening
Create a new debugMode configuration element, set the value to CLIENT, and run the package Maven goal
Start HiveMQ and wait until it starts
Verify that the debugger is connected