Vert.x (Java 8 Flavored)

by Tim Dalton, Principal Software Engineer

September 2014

Introduction

Vert.x is a platform for running HTTP and TCP services. These services are normally implemented using callbacks that handle the results of otherwise blocking operations such as communicating with a database or file I/O. This if often referred to as "event-driven" processing and has been popularized by Node/JS. Use of event-driven services allows for greater scalability due to greater efficiency using threads. A single thread can be used by many services. Vert.x brings event-driven services to the JVM.

Below is a example of a very simple web server implemented in Vert.x:

package tfd.sett.vertx;
 
import org.vertx.java.core.Handler;
import org.vertx.java.core.http.HttpServerRequest;
import org.vertx.java.platform.Verticle;
 
public class SimpleExampleNoLambdas extends Verticle {
 
    @Override
    public void start() {
        vertx.createHttpServer().requestHandler(new Handler<HttpServerRequest>() {
            @Override
            public void handle(HttpServerRequest httpServerRequest) {
                httpServerRequest.response().end("Hello World");
            }
        }).listen(8080);
    }
}

The above example creates a simple HTTP server that listens on port 8080 and returns a text response of "Hello World".

Though Vert.x was created before Java 8 was released, many of the interfaces have a single abstract method that allows them to be replaced with lambda expressions. Below is the same as above with the handler replaced with a lambda expression:

package tfd.sett.vertx;
 
import org.vertx.java.platform.Verticle;
 
public class SimpleExample extends Verticle {
 
    @Override
    public void start() {
        vertx.createHttpServer().requestHandler(httpServerRequest -> {
            httpServerRequest.response().end("Hello World");
        }).listen(8080);
    }
}

Though Vert.x does feature a command line interface for starting instances, there is also a Maven archetype to allow Vert.x to run via Maven only. The attached zip uses Maven so there is no need to download Vert.x itself to execute the examples, just Maven. To execute the examples, the JAVA_HOME environment variable needs be set to the location of Java 8 on the file system. Here are the Maven commands from the previous examples:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.SimpleExampleNoLambdas"

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.SimpleExample"

Open http://localhost:8080 to interact with the above examples.

Verticles

The basic "unit" of processing within Vert.x is called a Verticle. Most of the time verticles are event-driven and handlers spawned from them should not block since other verticles in that instance share the same thread. Verticles can be deployed as "Worker" verticles that can perform blocking operations by running within their own thread pool. For this reason worker verticles are not as scalable as event-driven verticles. Many verticles can deployed within an instance of Vert.x.

Event Bus

Vert.x uses an event bus by which verticles can communicate with each other. Addresses for messages on the event bus are simply strings. Communication can be done via publish and subscribe or point to point. Message types supported include string, primitive types and instances of a buffer type implemented in Vert.x.

Below is example of multiple message handlers for the same address on the event bus. When messages are sent point to point to multiple handlers, the handlers will be invoked in round robin manner. Messages that are published are sent to all handlers.

package tfd.sett.vertx;
 
import org.vertx.java.platform.Verticle;
 
public class MessagingExample extends Verticle {
 
    @Override
    public void start() {
        container.deployVerticle("tfd.sett.vertx.MessagingExample$Server");
 
        vertx.eventBus().registerHandler("message.handler", message -> {
            System.out.println("Handler 1 got a message = " + message.body());
        });
 
        vertx.eventBus().registerHandler("message.handler", message -> {
            System.out.println("Handler 2 got a message = " + message.body());
        });
 
        vertx.eventBus().registerHandler("message.handler", message -> {
            System.out.println("Handler 3 got a message = " + message.body());
        });
    }
 
    public static class Server extends Verticle {
        @Override
        public void start() {
            vertx.createHttpServer().requestHandler(httpServerRequest -> {
                if (httpServerRequest.params().contains("send")) {
                    vertx.eventBus().send("message.handler", httpServerRequest.params().get("send"));
                }
                if (httpServerRequest.params().contains("publish")) {
                    vertx.eventBus().publish("message.handler", httpServerRequest.params().get("publish"));
                }
                httpServerRequest.response().end("OK");
            }).listen(8080);
        }
    }
}

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.MessagingExample"

Using a browser, messages get sent to the even bus via urls like http://localhost:8080?send=this+has+been+sent
and http://localhost:8080?publish=this+has+been+published.

One use for the event bus is when an event driven verticle needs to send work to a worker verticle that performs a blocking operation. The below example shows a verticle deploying two other verticles, one of which is a worker.

package tfd.sett.vertx;
 
import org.vertx.java.core.Handler;
import org.vertx.java.core.eventbus.Message;
import org.vertx.java.platform.Verticle;
 
public class WorkerVerticleExample extends Verticle {
    @Override
    public void start() {
        container.deployVerticle("tfd.sett.vertx.WorkerVerticleExample$Server");
        container.deployWorkerVerticle("tfd.sett.vertx.WorkerVerticleExample$Worker");
    }
 
    public static class Server extends Verticle {
        @Override
        public void start() {
            vertx.createHttpServer().requestHandler(httpServerRequest -> {
                vertx.eventBus().send("worker.handler", httpServerRequest.path(), (Handler<message<string>>) reply -> {
                    httpServerRequest.response().end(reply.body());
                });
            }).listen(8080);
        }
    }
 
    public static class Worker extends Verticle {
        @Override
        public void start() {
            vertx.eventBus().registerHandler("worker.handler", message -> {
                try { Thread.sleep(1000); } catch (InterruptedException ex) { }
                message.reply("Hello World : " + message.body().toString());
            });
        }
    }
}
</message<string>

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.WorkerVerticleExample"

In the above example, the Server verticle receives an HTTP request and sends a message to the Worker verticle which has a blocking operation (Thread.sleep). Upon completion, the worker verticle's reply is sent back to the server vertical to be included in the HTTP response.

Shared Data

Vert.x supports sharing of maps and sets between multiple verticles. These data structures are copied when retrieved to prevent multiple verticles from mutating the contents.

Below is an example of a handler in two different verticles communicating using a shared map. The response will be the path on the other handler's most recent request or blank if there isn't one. Run this example and open two browser tabs to http://localhost:8080/foo and http://localhost:8081/bar. Refresh the browser and change paths to see the data being shared being the verticles.

package tfd.sett.vertx;
 
import org.vertx.java.platform.Verticle;
 
public class SharedData extends Verticle {
 
    @Override
    public void start() {
        container.deployVerticle("tfd.sett.vertx.SharedData$Server1");
        container.deployVerticle("tfd.sett.vertx.SharedData$Server2");
 
    }
 
    public static class Server1 extends Verticle {
        @Override
        public void start() {
            vertx.createHttpServer().requestHandler(httpServerRequest -> {
                if (!"/favicon.ico".equals(httpServerRequest.path())) {
                    vertx.sharedData().getMap("map").put("server1", httpServerRequest.path());
                }
                Object server2Path = vertx.sharedData().getMap("map").get("server2");
                httpServerRequest.response().end(server2Path != null ? server2Path.toString() : "");
            }).listen(8080);
        }
    }
 
    public static class Server2 extends Verticle {
        @Override
        public void start() {
            vertx.createHttpServer().requestHandler(httpServerRequest -> {
                if (!"/favicon.ico".equals(httpServerRequest.path())) {
                    vertx.sharedData().getMap("map").put("server2", httpServerRequest.path());
                }
                Object server1Path = vertx.sharedData().getMap("map").get("server1");
                httpServerRequest.response().end(server1Path != null ? server1Path.toString() : "");
            }).listen(8081);
        }
    }
}

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.SharedData"

Multiple Instances

Vert.x supports multiple instances to scale across multiple cores. Usually the number of instances will be the number of cores on the host processor. Verticle instances are single-threaded and will only use a single processor core. Multiple instances allow Vert.x to take advantage of multiple cores. The number of instances can be specified as an argument when starting a verticle:

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.SimpleExample -instances 4"

Vert.x will handle multiplexing requests between the same verticle in different instances in a round robin manner.

Routing

Vert.x has a RouteMatcher class where different handlers can be registered for different paths on the HTTP request. Route matchers have methods corresponding to the various HTTP actions (GET, POST, etc) and can match on specific paths or a regular expression. There is a noMatch method where a handler can be specified to handle any request not matched.

The example below uses a RouteMatcher to serve up the "favicon.ico" from the file system and let other requests return the "Hello World" string:

package tfd.sett.vertx;
 
import org.vertx.java.core.http.RouteMatcher;
import org.vertx.java.platform.Verticle;
 
public class RouteMatcherExample extends Verticle {
    @Override
    public void start() {
        RouteMatcher routeMatcher = new RouteMatcher();
 
        routeMatcher.get("/favicon.ico", req -> {
            req.response().sendFile(this.getClass().getResource("/heart.ico").getFile().replaceAll("^/[A-Z]:", ""));
        });
 
        routeMatcher.noMatch(req -> {
            req.response().end("Hello World");
        });
 
        vertx.createHttpServer().requestHandler(routeMatcher).listen(8080);
    }
}

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.RouteMatcherExample"

Navigating to http://localhost:8080/ should display a heart shaped icon on the tab or window provided a reasonably modern browser is being used.

Timers

Vert.x supports timers that can invoke handlers on one time basis after an initial delay or on a periodic basis.

package tfd.sett.vertx;
 
import org.vertx.java.platform.Verticle;
 
public class TimerExample extends Verticle {
 
    @Override
    public void start() {
        vertx.setTimer(15000, timerId -> {
            System.out.println("Fifteen seconds later...");
        });
 
        vertx.setPeriodic(3000, timerId -> {
            System.out.println("Every three seconds this is printed");
        });
    }
}

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.TimerExample"

TCP Servers

Vert.x is more than just HTTP. Support for TCP (and UDP) servers in built into Vert.x.

package tfd.sett.vertx;
 
import org.vertx.java.core.net.NetServer;
import org.vertx.java.platform.Verticle;
 
public class NetServerExample extends Verticle {
    @Override
    public void start() {
        NetServer netServer = vertx.createNetServer();
 
        netServer.connectHandler(sock -> {
            System.out.println("A client has connected!");
 
            sock.dataHandler(buffer -> {
                System.out.print(buffer.toString());
            });
 
            sock.closeHandler( aVoid -> {
                System.out.println("A client has closed");
            });
        });
 
        netServer.listen(8082);
    }
}

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.NetServerExample"

One can connect to the NetServer in the example above using telnet:

telnet localhost 8082

The server simply echoes characters typed in the telnet client.

Clustering

Vert.x allows multiple JVM instances to form a cluster sharing the event bus.

package tfd.sett.vertx;
 
import org.vertx.java.platform.Verticle;
 
public class RemoteHandlerExample extends Verticle {
 
    @Override
    public void start() {
        vertx.eventBus().registerHandler("message.handler", message -> {
            System.out.println("Remote Handler 1 got a message = " + message.body());
        });
    }
}

To execute this example along with the MessageExample above in a cluster use two command prompts:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.MessagingExample -cluster"

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.RemoteHandlerExample -cluster"

Client-Side Event Bus

The event bus in Vert.x can be accessed by Javascript code running in the client. This allows the client to send and receive messages from verticles running on the server. To accomplish this Vert.x implements a SockJS server to send and receive data from the client:

package tfd.sett.vertx;
 
import org.vertx.java.core.Handler;
import org.vertx.java.core.http.HttpServer;
import org.vertx.java.core.http.HttpServerRequest;
import org.vertx.java.core.http.RouteMatcher;
import org.vertx.java.core.json.JsonArray;
import org.vertx.java.core.json.JsonObject;
import org.vertx.java.platform.Verticle;
 
public class ClientMessagingExample extends Verticle {
    @Override
    public void start() {
        HttpServer server = vertx.createHttpServer().requestHandler(
            new RouteMatcher()
                .get("/vertxbus-2.1.js", new FileHandler("/vertxbus-2.1.js"))
                .get("/favicon.ico", new FileHandler("/heart.ico"))
                .noMatch(new FileHandler("/clientevents.html"))
        );
 
        vertx.eventBus().registerHandler("message.handler", message -> {
            System.out.println("ClientMessagingExample got a message = " + message.body());
        });
 
        JsonArray permitted = new JsonArray().add(new JsonObject().putString("address", "message.handler"));
        vertx.createSockJSServer(server).bridge(new JsonObject().putString("prefix", "/eventbus"), permitted, permitted);
        server.listen(8080);
    }
 
    public static class FileHandler implements Handler<HttpServerRequest> {
        private final String file;
 
        public FileHandler(String file) {
            this.file = file;
        }
 
        @Override
        public void handle(HttpServerRequest httpServerRequest) {
            httpServerRequest.response().sendFile(this.getClass().getResource(file).getFile().replaceAll("^/[A-Z]:", ""));
        }
    }
}

Here is some JavaScript to send and publish events:

var eventBus;
 
function registerEventBus() {
  eventBus= new vertx.EventBus('http://localhost:8080/eventbus');
      eventBus.onopen = function() {
          eventBus.registerHandler('message.handler', function(message) {
              alert(message);
          });
      }
}
 
function sendMessage() {
  eventBus.send('message.handler', 'sent from the client');
}
 
function publishMessage() {
  eventBus.publish('message.handler', 'published by the client');
}

To execute:

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.ClientMessagingExample"

Open http://localhost:8080/ in browser and hit "send" and "publish" buttons.

The ClientMessageExample can be executed in a cluster along with the RemoteHandlerExample. Since the "message.handler" is used for the event bus address for both, the messages should get distributed.

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.ClientMessagingExample -cluster"

mvn compile exec:java -Dexec.mainClass="org.vertx.java.platform.impl.cli.Starter" -Dexec.args="run tfd.sett.vertx.RemoteHandlerExample -cluster"

Other Features

Notable features of Vert.x not covered here.

Module System

Re-usable collections of verticles and other components can be grouped into modules. Modules can be composed to within an Vert.x application. They also provide an extension mechanism for Vert.x.

Polyglot

Vert.x has modules to support verticles written in Groovy, Python (Jython), Ruby (JRuby) and Javascript (Rhino). Clojure and Scala support are planned as well.

Summary

Vert.x is good candidate for uses where HTTP as well TCP and UDP services need to be scalable across multiple hosts or embedded in a larger application. Another strong characteristic is simplicity when it comes to implementing services and handling concurrency.

References

[1] Vert.x
http://vertx.io/
[2] Example Project
vertxeval18.zip

Software Engineering Tech Trends (SETT) is a regular publication featuring emerging trends in software engineering.