Home

Awesome

vertx:hot

Hot reloading of Vert.x Verticles for Maven and Buck

Build Status Join the chat at https://gitter.im/dazraf/vertx-hot

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.

This plugin can speed up your dev cycle in popular build systems, such as Maven.

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

Maven Instructions

Step 1: Download

Release versions of the Maven 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

Optional

<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:

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.

Buck Instructions

Buck is an efficient build system capable of identifying and recompiling only what it absolutely has to.

Before you rush off to switch from Maven/Gradle to Buck, it's important to bear in mind that Buck is not (and doesn't intend to be) as featureful as Maven. If you're used to transitive dependency retrieval, haven't heard of the concept of checking-in dependencies, leverage multitudinous Maven plugins, have developed custom Maven plugins, regularly rely on your build system's strong IDE integration, or just need things to work "out-of-the-box", then Buck might not be for you. However, if you are looking for outrageously fast builds, are prepared to rethink your project structure, and if the concepts behind Buck resonate for you, then you may want to give it a try.

The Buck support in vertx-hot is presently both limited and inefficient, but is hopefully sufficient to be of use to simple projects. As always, feature and pull requests are most welcome.

Step 1: Get the jar

The vertx-hot-buck build produces a fat-jar, to make inclusion from Buck projects fairly simple.

A few dependencies have been excluded, either due to shading complexities or to improve flexibility:

If you're checking-in dependencies to your VCS, as per the recommended Buck methodology, then:

  1. Store the vertx-hot-buck jarfile in your lib directory
  2. Reference it using a prebuilt_jar rule:
prebuilt_jar(
  name = 'vertx-hot-buck',
  binary_jar = 'lib/vertx-hot-buck.jar'
)

If you fetch libraries from an m2 compatible repository, then you can include a corresponding remote_file rule to perform the fetch.

Step 2: Add to your project

An easy way to configure a buck hot deploy target is with a dedicated main class.

You'll likely want to configure the logger:

System.setProperty("vertx.logger-delegate-factory-class-name", "io.vertx.core.logging.SLF4JLogDelegateFactory");

Then configure your hot deployment:

BuckHotDeployBuilder.create()
  .withBuildTarget("//my-service:bin")
  .withProjectRootPath(".")
  .withHotDeployConfig(new HotDeployParameters()
    .withBuildResources(true)
    .withCompileSourcePaths(asList("my-service/java"))
    .withNotificationPort(9588)
    .withVerticleReference("io.dazraf.myservice.MyVerticle")
  )
  .build()
  .run();

Executing the main method, with an appropriate classpath, will start the hot deployment.

The buck deployment parameters are:

Required

Optional

The hot deployment configuration options are described in the Maven installation instructions.

Design Notes

sequence diagram

Contributors

With many thanks: