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 with the Packing profile checked.

Package Extension

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

Package 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

An important part of any kind of software development, including the development of a customer HiveMQ extension, is debugging your 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.
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.




Debugging with IntelliJ

These are the necessary steps to open a debugging session for your HiveMQ Extension, utilizing a local HiveMQ 4 instance and IntelliJ.

  • Download and install HiveMQ

  • Open the HIVEMQ_HOME/bin/run.sh with the text editor of your choice

  • Add the following JAVA_OPTS at line 42

  • JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005” As a result the excerpt of your run.sh should look like this:

# JMX Monitoring
    JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"
    JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005"
    # Uncomment for enabling Diagnostic Mode
    #JAVA_OPTS="$JAVA_OPTS -DdiagnosticMode=true”

As a result, next time you startup this HiveMQ process, the startup will hold, start listening on port 5005 for a debugger and resume after a debugging process has attached itself.
This is the preferred way of debugging especially when some of the custom business logic is already applied at HiveMQ startup.

  • Start HiveMQ by execute this newly edited run.sh

  • Package and install your HiveMQ Extension

  • Create new run configuration in IntelliJ for debugging purposes Add Configuration…​+RemoteOK

Add Run Config
  • Use settings Attach to remote JVM , localhost, 5005 and Command line arguments agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005

Configure Run Config
  • Create a break point at the position of your source code you would like to debug

  • Start the newly created configuration by pressing on the bug symbol

Don’t forget to name your run configuration appropriately.
Start Connfig
  • That’s it. HiveMQ will startup as soon as it recognizes the attached debugger process, load your extension and you are able to debug at your break point (1).

Success!




Debugging with Eclipse

These are the necessary steps to open a debugging session for your HiveMQ Extension, utilizing a local HiveMQ 4 instance and Eclipse.

  • Download and install HiveMQ

  • Open the HIVEMQ_HOME/bin/run.sh with the text editor of your choice

  • Add the following JAVA_OPTS at line 42

  • JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005” As a result the excerpt of your run.sh should look like this:

# JMX Monitoring
    JAVA_OPTS="$JAVA_OPTS -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=9010 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false"
    JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5005"
    # Uncomment for enabling Diagnostic Mode
    #JAVA_OPTS="$JAVA_OPTS -DdiagnosticMode=true”

As a result, next time you startup this HiveMQ process, the startup will hold, start listening on port 5005 for a debugger and resume after a debugging process has attached itself.
This is the preferred way of debugging especially when some of the custom business logic is already applied at HiveMQ startup.

  • Start HiveMQ by execute this newly edited run.sh

  • Package and install your HiveMQ Extension

  • Create a break point at the position of your source code you would like to debug

  • Create new run configuration in Eclipse for debugging purposes

Add Run Config
  • Select Remote Java Application, Your Extension, localhost, Port:5005 and press Debug

Configure Run Config
  • That’s it. HiveMQ will startup as soon as it recognizes the attached debugger process, load your extension and you are able to debug at your break point (1).

Success!