Sunday, March 11, 2018

Vertx Programming Style : Your Reactive Web Companion REST API Explained

Vertx provides a lot of options to program in a light weight environment, like node.js . However, It could be little confusing for new users to choose which method to adopt for creating REST API.

There are different models to adopt while programming in vertx. They are explained below with easy to understand diagrams.

P.S - The heart of vertx programming is a reference to vertx object which could be obtained statically or as an inherited member with a verticle that extends the AbstractVerticle class. Now you know where to get the vertx object. Let's dive further.

Different Models of programming in vertx falls into the following categories as below, I am adding some funny names to each model :) :-

  1. FaceToFace Approach
  2. Matchmaker Approach
  3. Matching Coach Approach

Model 1 - FaceToFace Approach:

As shown in the diagram, in this model client sends the events in forms of http requests which are buffered to server verticle via a Router. A router could be obtained by using Router.router(vertx)

Now we can configure the router to handle http requests. Careful, router handlers are synchronous call. To run blocking calls or any async operations, please use executeBlocking or adopt Model#2

Model #2 - Matchmaker Approach:
As the name suggests, you can't talk to the other person directly, you will have to go through the dating match maker which is the event bus. This is model is useful when you have a lot of micro services running on different machines or you want to modularize your code in a single machine. A message has header, body, address and by calling message.reply(Object), the receiver verticle can send response back to the sender.

Model 3: Matching Coach Approach:

Here The matchmaker becomes a coach too who will help you how to connect other verticle. It helps by code generation to bind service with event bus so that it would be easier to call service methods.

The main idea is a service name Service (java interface) and corresponding implementation Service Implementation to be exposed as a REST API. But it can't be that straight forward in vertx as in spring web or other frameworks. For Service interface to be exposed, you need to create a AsyncService interface and it's implementation which will mimic Service methods but the signatures will be little different.

Example: In Service interface, you have a method as below:
public User getUser(final String verificationToken) {...}

In async service interface, the same looks like, 
void getUser(String verificationToken, Handler<AsyncResult<User>> resultHandler)

Here we adding an extra argument to the method in form of a vertx Handler that returns an AsyncResult which makes it possible for non-blocking call. Also the return type is void. The result could obtained from the client side using the resultHandler callback.

Please leave your comments below.

Happy Coding!


  1. Your funny names are quite good. Thank you. Keep up the good work.

  2. I really like this post and would like to share a content to you free of cost. I have written an original and 100% unique article on the topic How To Build A Web Application With Node JS. The article is of length 1000 words if you agree to publish it here I can send it to you right now. Please reply me on I shall be looking forward to your reply soon. ...Thanks and regards