Writing Verticles

JavaScript verticles are implemented either as CommonJS modules or NPM modules.

Important
JavaScript support requires Java 1.8.0_45+. You can check your Java version with java -version. Please update if needed.

Here’s an example JavaScript verticle written as a CommonJS module.

JavaScript verticles will have the following globals pre-set as a convenience:

  • vertx - A reference to the Vertx object

  • console A reference to the console object

// the vertx and console objects can be used directly as:
vertx.setPeriodic(1000, function() {
  console.log('Timer has fired');
});

// Optional - called when verticle is undeployed
exports.vertxStop = function() {
  console.log('stop called');
}

When the verticle is deployed the body of the script will be executed.

Optionally a vertxStop callback can be defined to be notified when the verticle is undeployed. Notice that such a registration is made using exports.vertxStop = function() { …​ }.

The console

In addition to the vertx object, JavaScript verticles have access to a console object that let them print messages. The messages are printed on Java System.out and System.err:

console.log("hello"); // Print on System.out
console.warn("warning, something wrong is happening"); // Print on System.err
console.error("something terrible happened"); // Print on System.err

Defining a start method

By default, when your verticle is deployed, vert.x execute the body of the javascript file. However, you can define a start method as follows:

exports.vertxStart = function() {
 console.log("This is my verticle and it is starting...");
}

As for vertStop seen above, the method is defined on the exports object.

Important
Even with a vertxStart method defined, vert.x executes the body of the file.

Asynchronous Verticle start and stop

Sometimes you want to do something in your verticle start-up which takes some time and you don’t want the verticle to be considered deployed until that happens. For example you might want to deploy other verticles in the start method.

You can’t block waiting for the other verticles to deploy in your start method as that would break the Golden Rule.

So how can you do this?

The way to do it is to implement the asynchronous start method. This version of the method takes a Future object as a parameter. When the method returns the verticle will not be considered deployed yet. Some time later, after you’ve done everything you need to do (e.g. start other verticles), you can call complete on the Future (or fail) to signal that you’re done.

Here’s an example:

exports.vertxStartAsync = function(startFuture) {
 vertx.deployVerticle("verticle.js", function(res, err) {
   if (err) {
     startFuture.fail();
   } else {
     startFuture.complete();
   }
 });
};

Similarly, there is an asynchronous version of the stop method too. You use this if you want to do some verticle cleanup that takes some time.

exports.vertxStopAsync = function(stopFuture) {
 obj.doSomethingThatTakesTimes(function(r, err) {
   if (err) {
     stopFuture.fail();
  } else {
     stopFuture.complete();
  }
 });
};

INFO: You don’t need to manually undeploy child verticles started by a verticle, in the verticle’s stop method. Vert.x will automatically undeploy any child verticles when the parent is undeployed.