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. |
The package lifecycle builds an <your-extension-version>-distribution.zip file inside the target
folder of your project.
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.
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. |
<?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.
|
Name | Default | Mandatory | Description |
---|---|---|---|
|
The name of your local HiveMQ directory. If you have not yet downloaded HiveMQ, you can download the current version of HiveMQ here. |
||
|
hivemq.jar |
The name of the HiveMQ jar file in the bin directory. |
|
|
{artifactId}-{version}-distribution.zip |
The name of the extension zip file. |
|
|
target |
The directory in which your extension is located. |
|
|
true |
Defines whether the messages logged from HiveMQ are visible on the console. To view messages, set to true. |
|
|
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. |
|
|
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. |
|
|
5005 |
In SERVER mode, the debug port on which the debug server starts. In CLIENT mode, the debug port to which the client connects. |
|
|
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