vertx:hot

A Maven plugin for hot reload of Vert.x Verticles

---

Contents

1. Background
2. Aims
3. Instructions
4. Example Project
5. Design Notes
6. Contributors

Background

Vert.x is an incredible toolkit for developing high-performance applications.

If you use Maven as well, then this plugin can speed up your dev cycle.

Write your code and see the changes auto reload into your JVM. Fully debuggable.

This plugin was originally written for personal use. Its shared here under the MIT licence.

Contributions most gratefully received and recognised.

Aims

1. Detect source changes
2. compile stale targets
3. Hot Reload
4. Full Debug without needing to attach to secondary processes
5. Intuitive integration with Maven toolchain
6. Fast at least much faster than using a manual workflow

Instructions

Step 1: Download

Release versions of the plugin are available in Maven Central. Snapshots are available in Sonatype. Zip'd releases are available here.

Please note: the latest version of the plugin depends on vert.x 3.1.0.

Step 2: Add to your project

Add the following to your project pom.xml:

<plugin>
    <groupId>io.dazraf</groupId>
    <artifactId>vertx-hot-maven-plugin</artifactId>
    <version>2.1.0</version>
    <configuration>
        <verticleReference>class or service name</verticleReference>
        <configFile>config filename</configFile>
    </configuration>
</plugin>

The configuration has the following elements:

Required

• verticleReference - either the fully-qualified reference to the top-level verticle of your application or a service reference.

Optional

• configFile - the class path to the verticle configuration file. When loaded, vertx:hot will add the property "devmode": true.

• liveHttpReload - when true, all web pages served by the application verticles will auto reload when any source is changed. default: true

• buildResources - when set to true, any change to files under the resource directories will trigger a compile. Use this if your resources generate sources. default: false

• notificationPort - websocket port for browser notifications. Used in conjunction with liveHttpReload: true. Default is 9999.

• extraPaths - list of additional paths to be watched. This has a list of <extraPath> elements. Example as follows:

<extraPaths>
  <extraPath>
    <path>specialPath/causesRedeploy.md</path>
    <!-- default -->
    <!-- <action>Redeploy</action> -->
  </extraPath>
  <extraPath>
    <path>specialPath/causesCompile.md</path>
    <action>Recompile</action>
  </extraPath>
  <extraPath>
    <path>specialPath/causesRefresh.md</path>
    <action>Refresh</action>
  </extraPath>
</extraPaths>

Step 3: Run it

You can run it either on the command line with:

mvn vertx:hot

Or, in your favourite IDE:

• For any IDE you'll need a locally installed maven installation. Bundled / Embedded maven installations do not work.

• IntelliJ IDEA:

  • Run - open the Maven side-bar, expand the Plugins/vertx section and double-click on vertx:hot goal. Any changes to your project's main source (e.g. src/main) will cause a hot deploy.
  • Debug - right-click on the vertx:hot goal and select Debug.

• Eclipse:

  • Run - create maven build runner for vertx:hot goal. For Eclipse Mars on OS X, I found I had to set the JAVA_HOME environment variable in the runner. Once setup, Run it.
  • Debug - as above, but instead of Run, Debug

Step 4: Stopping the plugin

Press either: <Enter> or Ctrl-C.

Example Project

There are two simple test project under example1 and example2. The latter is an adaption of the excellent ToDo App by Scotch, with a vert.x reactive flavour.

To run either:

1. You will need bower on your path.
2. After running mvn clean install in the parent directory
3. cd example1 or cd example2
4. mvn vertx:hot
5. Browse to http://localhost:8888
6. Open up the project in your favourite IDE/Editor and try changing some code or static resources
7. The browser will automatically reload. The IDE/shell console will show the unload | recompile | reload activity.

Design Notes

Contributors

With many thanks:

• illuminace