Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hivemq/hivemq-hello-world-plugin

A Hello World Plugin for getting started with plugin development for the HiveMQ MQTT broker
https://github.com/hivemq/hivemq-hello-world-plugin

Last synced: 5 days ago
JSON representation

A Hello World Plugin for getting started with plugin development for the HiveMQ MQTT broker

Awesome Lists containing this project

README 

        
:hivemq-link: http://www.hivemq.com

:hivemq-plugin-docs-link: https://www.hivemq.com/docs/3.4/plugins/introduction.html

:hivemq-plugin-docs-archetype-link: https://www.hivemq.com/docs/3.4/plugins/get-started-with-maven-archetype.html#maven-archetype

:hivemq-blog-tools: http://www.hivemq.com/mqtt-toolbox

:hivemq-callbacks-overview-link: https://www.hivemq.com/docs/3.4/plugins/callbacks.html#overview

:maven-documentation-profile-link: http://maven.apache.org/guides/introduction/introduction-to-profiles.html

:hivemq-support: http://www.hivemq.com/support/

:extension: https://github.com/hivemq/hivemq-hello-world-extension



== HiveMQ Hello World Plugin



NOTE: HiveMQ 4 uses a new extension system. This HiveMQ 3 plugin is not compatible with HiveMQ 4. The new version can be found {extension}[here].



=== Purpose



This Hello World plugin is a showcase for the kind of functionality that is possible within the {hivemq-link}[HiveMQ] plugin environment. There is {hivemq-plugin-docs-archetype-link}[a Maven Archetype available] to generate a much more basic plugin from the IDE.



We strongly recommend to read the {hivemq-plugin-docs-link}[HiveMQ Plugin Documentation] to grasp the core concepts of HiveMQ plugin development.



=== What you'll get



This Hello World plugin implements a few simple HiveMQ Callbacks to get you started:



* A callback when a client connects

* A callback when a client disconnects

* A callback when a client publishes something

* A callback when HiveMQ starts

* A scheduled callback that gets executed every 5 sec



There are also some advanced callbacks, which implement more complex use cases:



* A callback that shows the async Subscription Service

* A scheduled callback using the RetainedMessages Service

* A callback that shows the Client Service and Publish Service



Also, this hello world plugin can reads configurations from a properties file (and reloads it every 5 minutes).



There's a Maven profile configured which starts HiveMQ with your plugin. Just enable the profile and run the +package+ Maven phase.



IMPORTANT: Don't forget to set the path to your HiveMQ installation in the +pom.xml+. There's a "FIXME:" in the +pom.xml+ to remind you of that.



The plugin is documented with javadoc which explains what's going on. Please don't forget to read the extensive {hivemq-plugin-docs-link}[HiveMQ Plugin Documentation].



=== Trying the plugin



. Execute the +package+ goal from Maven with the profile _RunWithHiveMQ_ activated. (Need help?: Consult: {maven-documentation-profile-link}[The maven documentation])

. Now HiveMQ should be running *with* your plugin installed.

. Connect with a {hivemq-blog-tools}[MQTT client] of your choice and publish something. You should see some log output.



=== Next steps



Awesome, you got your first HiveMQ plugin working. Now grab a coffee and prepare for the next steps:



* Read about the available HiveMQ callbacks {hivemq-callbacks-overview-link}[here].

* Implement a great plugin. Bring your JDBC driver and do some database fun. Integrate with your favourite web service. There are no limits :-)

* Blog about your awesome plugin. Tell us and if you like we can add your plugin to the plugin registry on http://www.hivemq.com



=== Need help?



If you encounter any problems, we are happy to help. The best place to get in contact is our {hivemq-support}[support].



= Contributing



If you want to contribute to HiveMQ Hello World Plugin, see the link:CONTRIBUTING.md[contribution guidelines].



= License



HiveMQ Hello World Plugin is licensed under the `APACHE LICENSE, VERSION 2.0`. A copy of the license can be found link:LICENSE.txt[here].