Vert.x - From zero to (micro)-hero

We need a JDK 8+ installed on our machine. Latest JDK can downloaded from:

You can use either Oracle JDK or OpenJDK.

We recommend you to use an IDE. You can use Eclipse, IntelliJ or Netbeans.

You can import the code in your IDE as a Maven project. You can refer to your IDE documentation to know how to import Maven projects.

For Eclipse:

You are going to see a couple of compilation errors. This is because Eclipse does not mark the src/main/generated directories as source root by default. Right-click on portfolio-service/src/main/generated and select Build Path → Use as Source Folder.

The build is managed using Apache Maven. Compile everything using:

As said previously, Vert.x does not depend on Apache Maven. You can use any build tool (or even no build tool).

It’s about time to start. If you remember the microservice section, we need some service discovery mechanism. Fortunately, Vert.x offers a service discovery mechanism. To let every component discover the services, it needs to store the service record in a location that every one can access.

By default, Vert.x service discovery is going to use a distributed map accessible by all the members of the cluster. So, when you start your Vert.x application and enable the cluster mode, it joins a cluster. This cluster lets nodes:

In our context, you don’t need to configure anything. The lab provides a cluster configuration using unicast and the 127.0.0.1 IP (so you won’t see the services from your neighbors). The cluster is built on top of Hazelcast. You can check the configuration in vertx-workshop-common/src/main/resources/cluster.xml.

Let’s have a look to the project, as every other project are structured the same way.

Let’s start with the pom.xml file. This file specifies the Maven build:

A fat-jar (also called uber jar or shaded jar) is a convenient way to package a Vert.x application. It creates a über-jar containing your application and all its dependencies, including Vert.x. Then, to launch it, you just need to use java -jar …​., without having to handle the CLASSPATH. Wait, I told you that Vert.x does not dictate a type of packaging. It’s true, fat jars are convenient, but it’s not the only way, you can use plain (not fat) jars, OSGi bundles…​

The created fat-jar is configured to use a main class provided in vertx-workshop-common (io.vertx.workshop .common.Launcher). This Launcher class creates the Vert.x instance, configure it and deploys the main-verticle. Again, it’s just a convenient way, you can use your own main class.

As you may have noticed, the code is structured in 3 verticles, but what are these? Verticles is a way to structure Vert.x application code. It’s not mandatory, but it is quite convenient. A verticle is a chunk of code that is deployed on top of a Vert.x instance. A verticle has access to the instance of vertx on which it’s deployed, and can deploy other verticles.

Let’s open the GeneratorConfigVerticle class, and look at the start method:

Verticles can retrieve a configuration using the config() method. Here it gets the details about the companies to simulate. The configuration is a JsonObject. Vert.x heavily uses JSON, so you are going to see a lot of JSON in this lab. For each company found in the configuration, it deploys another verticle with the extracted configuration. Finally, it deploys another verticle providing a very simple HTTP API.

The last part of the method is about the service discovery mentioned in the microservice section. This component generates quotes sent on the event bus. But to let other components discover where the messages are sent (where means on which address), it registers it. market-data is the name of the service, ADDRESS is the event bus address on which the messages are sent. The last argument is a Handler that is notified when the registration has been completed. The handler receives a structure called AsyncResult.

Remember, Vert.x is promoting an asynchronous, non-blocking development model. Publishing the service may take time (actually it does as it creates a record, write it to the backend, and notifies everyone), as we cannot block the event loop, the method is asynchronous. Asynchronous methods have a Handler as last parameter that is invoked when the operation has been completed. This Handler is called with the same event loop as the one having called the async method. As the asynchronous operation can fail, the Handler receives as parameter an AsyncResult telling whether or not the operation has succeeded. You will see the following patterns a lot in Vert.x applications:

If you remember the architecture, the quote generator also provides a HTTP endpoint returning the last values of the quotes (but, you are going to work on it). As the previous service, it needs to be published. For the publication it gives details on its locations (host, port…​):

It’s time for you to develop some parts of the application (I know you have pins and needles in your fingers). Open the RestQuoteAPIVerticle. It’s a verticle class extending AbstractVerticle. In the start method you need to:

Let’s do that…​.

First, let’s build the microservice fat-jar. In the terminal, execute:

Then, open a new terminal and launch:

This command launches the application. The main class we used creates a clustered Vert.x instance and reads the configuration from src/conf/config.json. This configuration provides the HTTP port on which the REST service is published (35000).

Let’s now open a browser and have a look to http://localhost:35000.

It should return something like:

It gives the current details of each quotes. The data is updated every 3 seconds, so refresh your browser to get the latest data.

Let’s now launch the dashboard. In another terminal, navigate to $project-home/trader-dashboard and execute:

Then, open your browser to http://localhost:8080. You should see:

Some parts have no content, and it’s expected as it’s just the beginning…​

So maybe you are not used to the financial world and words…​ Neither am I, and this is a overly simplified version. Let’s define the important fields:

You can check Wikipedia for more details.

Microservices are not only about REST. They can be exposed using any types of interactions, and Remote Procedure Calls is one of them. With RPC, a component can effectively send a request to another component by doing a local procedure call, which results in the request being packaged in a message and sent to the callee. Likewise, the result is sent back and returned to the caller component as the result of the procedure call:

Such interactions has the advantages to introduce typing, and so is less error-prone than unstructured messages. However, it also introduces a tighter coupling between the caller and the callee. The caller knows how to call the callee:

Traditional RPC exhibits an annoying drawback: the caller waits until the response has been received. This is definitely a blocking call, as it involves at least two network messages. In addition, it is not really designed for failures while distributed communications have many reasons to fail.

Fortunately, Vert.x proposes a different form of RPC: Async RPC. Async RPC follows the same principles as RPC, but instead of waiting for the response, it passes a Handler<AsyncResult<X> called when the result is received.

The AsyncResult notifies the Handler whether the invocation succeeded or failed. Upon success, the handler can retrieve the result.

Such async-RPC has several advantages:

To create an async RPC service, or event bus service, or service proxies, you first need a Java interface declaring the async methods. Open the io.vertx.workshop.portfolio.PortfolioService class.

The class is annotated with:

Let’s have a look at the first method:

This method lets you retrieve a Portfolio object. As explained above the method is asynchronous and so has a Handler parameter receiving an AsyncResult<Portfolio>. The other methods follows the same pattern.

The Portfolio object is a data object. Event bus proxies support a limited set of types, and for non-supported types, it must use data objects (please check the documentation for the whole list of supported types). Data objects are Java classes obeying to a set of constraints:

Let’s open the io.vertx.workshop.portfolio.Portfolio class to see how it looks like. As you can see, all the JSON handling is managed by converters that are automatically generated, so a data object is very close to a simple bean.

It’s nice to have an async interface for our service, but it’s time to implement it. We are going to implement three methods in this service:

Now that the service implementation is complete, let’s publish it ! First we need a verticle that creates the actual service object, registers the service on the event bus and publishes the service in the service discovery infrastructure.

Open the io.vertx.workshop.portfolio.impl.PortfolioVerticle class. In its start method is does what we just say:

1) Create the service object with:

2) Register it on the event bus using the ProxyHelper class:

3) Publish the service in the service discovery infrastructure to make it discoverable:

The publishEventBusService is implemented as follows:

Are we done ? No…​. We have a second service to publish. Remember, we are also sending messages on the event bus when we buy or sell shares. This is also a service (a message source service to be exact).

At the end of the start method, write the code required to publish the portfolio-events service. EVENT_ADDRESS is the event bus address.

Now we are done, and it’s time to build and run this service.

To build the project launch:

Then, launch it, in another terminal with:

Here you go, the portfolio service is started. It discovers the quotes service and is ready to be used.

Go back to the dashboard, and you should see some new services and the cash should have been set in the top left corner.

Well, it’s time to buy and sell some shares no ? Let’s do that in the next chapter.

Before seeing how these are implemented, let’s explain the absolutely illogic algorithm used by these traders:

It does not check whether or not it has enough shares or money, it just tries…​ This logic is implemented in io.vertx.workshop.trader.impl.TraderUtils.

The compulsive-trader project contains a main-verticle (io.vertx.workshop.trader.impl.MainVerticle) that is going to configure and deploy the traders:

The JavaCompulsiveTraderVerticle is deployed with some DeploymentOptions (1). This one sets the number of instances to 2, so Vert.x is not instantiating this verticle once, with twice (2 different objects). So, the previous code deploys three traders.

The Groovy verticle is deployed by passing the file name. The verticle file is in src/main/resources and will be located at the root of the fat-jar.

It’s now time to implement these verticles

Open the io.vertx.workshop.trader.impl.JavaCompulsiveTraderVerticle class. In the place of the TODO we need:

The Groovy trader is using the same trading logic, but this verticle is going to be developed in Groovy. To ease the understanding, the code is going to be very close to the Java version.

Open src/main/resources/GroovyCompulsiveTraderVerticle.groovy. This verticle is going to be a Groovy Script. So the content is the start method of the verticle. Vert.x also supports Groovy classes.

If you don’t know Groovy, just copy and paste the solution. If you do, you can try to implement the trader by yourself following the same logic as the Java trader:

It’s time to rebuild and restart our traders. Hit CTRL+C to stop the running trader. Then, rebuild with:

And launch the application with:

If you go back to the dashboard, you may start seen some moves on your portfolio. Now 3 traders are trying to make you (virtually) rich.

As said previously, Vert.x is asynchronous and you must never block the event loop. And you know what’s definitely blocking ? Database accesses and more particularly JDBC! Fortunately, Vert.x provides a JDBC client that is asynchronous.

The principle is simple (and is applied to all clients accessing blocking systems):

However, interactions with databases are rarely a single operation, but a composition of operations. For example:

So, we need a way to compose these operations, and report failures when required. This is what we are going to see in the Audit component.

The Audit service:

Interactions with the database use the vertx-jdbc-client, an async version of JDBC. So expect to see some SQL code (I know you love it).

Vert.x has an Rx version of its asynchronous API packaged with the io.vertx.rxjava prefix, e.g io.vertx.rxjava.core.Vertx is the Rx version of io.vertx.core.Vertx. The rxified version of Vert.x exposes the asynchronous methods as Single and the stream types as Observable.

Open the io.vertx.workshop.audit.impl.AuditVerticle class. The first important detail of this verticle is its start method. As the start method from the Java trader, the method is asynchronous, and report its completion in the given Future object:

Vert.x would consider the verticle deploy when the Future is valuated. It may also report a failure if the verticle cannot be started correctly.

Initializing the audit service includes:

So, it’s clearly 3 independent actions, but the audit service is started only when all of them has been completed.

Replace the TODO block with some code. This code should retrieves 3 single objects (from methods provided in the class) and wait for the completion of the three tasks. The three singles should be combined in one Single<MessageConsumer<JsonObject>>.

On success this single registers a message listener on the portfolio message source storing the operation in the database for each received message.

Its completion notifies Vert.x that the start process is completed (or successfully or not), it calls future.complete() and future.fail(cause).

Now our verticle extends the RxMicroServiceVerticle base class, this class provides the same helper method than MicroServiceVerticle using Rx singles.

We have mentioned that async method have a signature with a Handler as last parameter. There is an equivalent syntax that returns a Single object when the operations they are executing are completed:

Indeed, the caller can subscribe on the returned Single object to execute the async operation and be notified when the operation has completed or failed

Let’s implement the configureTheHTTPServer method following this pattern. In this method we are going to use a new Vert.x Component: Vert.x Web. Vert.x Web is a Vert.x extension to build modern web application. Here we are going to use a Router which let us implement REST APIs easily (à la Hapi or ExpressJS). So:

So, the caller can call this method and get a Single. It can subscribe on it to bind the server and be notified of the completion of the operation (or failure).

If you look at the retrieveThePortfolioMessageSource, you would see the very same pattern.

In the start method, we are calling initializeDatabase. Let’s look at this method using another type of action composition. This method:

All these operations may fail.

In the last paragraph we have seen methods returning Single. Chains are a composition of such functions:

The completion of a chain is a Single object. If one of the chained operation fails, this Single is marked as failed, otherwise it is completed with the result of the last operation:

So to use the composition pattern, we just need a set of Functions and a Single that would trigger the chain. Let’s create this Single first:

Then, we need compose the single with the flatMap method that is taking a SQLConnection as parameter and returns a single that contains the result of the database initialization.

The resultSingle is the final result providing a Single<List<Integer>> but we will return only a Single<Void> as the caller only cares about the global result and not the detail.

This is simple achieved with the map operations on the single:

And voilà!

You may ask why we do such kind of composition. Let’s implement a method without any composition operator (just using callbacks). The retrieveOperations method is called when a HTTP request arrives and should return a JSON object containing the last 10 operations. So, in other words:

The step (1) and (2) are asynchronous. (5) is asynchronous too, but we don’t have to wait for the completion. In this code, don’t use composition (that’s the purpose of this exercise). In retrieveOperations, write the required code using Handlers / Callbacks.

So obviously it’s possible too not use composition. But imagine when you have several asynchronous operation to chain, it become a callback hell very quickly. So, as a recommendation: use the Vert.x composition operators or use the rxified version of Vert.x API.

Let’s see how this works.

First you need to built it:

Then, you need to launch the application:

Restart and refresh the dashboard, and you should see the operations in the top right corner!

As mentioned in the previous section, Vert.x web is a Vert.x component to build web application. Its whole architecture is centered on the Router object. You create this router and configure the routes. For each route you configure the HTTP verb and the path and associate the Handler that is called when a matching request is received. The router is creates a follows:

Vert.x web provides a set of Handler for common tasks such as serving static files:

It serves all files from the webroot directory (default) or the server root. For example, webroot/index.html is served using the http://0.0.0.0:8080/index.html url.

Once the router is configured, you need a HTTP server and use the router to handle the requests:

It’s often required to implement a REST API on top of another one. This pattern can be very costly on traditional architecture as each call would block a thread until the call to this second REST API has completed. With Vert.x delegation is easy, asynchronous and non blocking.

For example in the dashboard, we want to retrieve the list of operations. This list is offered by the audit service. So in the dashboard we have this route definition:

And the handler is:

The audit service is retrieved in the verticle start method. If the service was not found, it returns a no audit service message. Otherwise, it uses the retrieved HTTP client to call the audit REST API. The response is simply sent back to the HTTP response.

The callAuditService method we have seen in the previous section does the job…​ but well, what we do know about distributed systems: they fail. It would be better to manage failures in this method. Vert.x proposes four ways to handle failures:

We have already covered the first point. In this section we cover the point 2 and 3. The next section is about circuit breakers.

Exception handlers are handlers receiving a Throwable parameter and are responsible for managing the reported error. It is used on object that does not called a Handler<AsyncResult<?>> such as on a HTTP request. During a HTTP request-response interaction, failures can happen at several places:

This last point is application specific and need to be handle by your code. The first two points are managed by exception handlers on the 1) HTTP request, 2) HTTP response objects. Vert.x uses two different handlers because the root issue is different.

Copy this method into another one called callAuditServiceWithExceptionHandler, and set the exceptionHandler on the HTTP request and HTTP response. Both should call the fail method on the RoutingContext parameter. In addition, on the request, configure the response timeout. The exception handler set on the request is called if the response cannot be retrieved before this timeout. Don’t forget to update the handler of the /operations route to call this new method.

Once done, build the dashboard with:

Then, launch it, in another terminal with:

Refresh the dashboard page. In the audit service terminal, stop the service and check how is reacting the dashboard (you can look at the AJAX request in the inspector/dev tools). Then, relaunch the audit service. What is happening ?

Circuit breaker is a reliability pattern that can be represented with a simple state machine:

This pattern is very popular in microservice based applications, because it recovers (if possible) from failures smoothly. The circuit breaker starts in the close state. The circuit breaker monitors an operation. Every time this operation fails, it increases a failure counter. When a threshold is reached, it goes to the open state. In this state, the required service is not called anymore, but a fallback is executed immediately. After some time, the circuit breaker goes into the half-open state. In this state, the operation is called for the first request. Other request are redirected to the fallback. If the operation fails, the circuit breaker goes back to the open state until the next attempt. If it succeed it goes back to the close state.

There are lots of implementations of circuit breakers, Netflix Hystrix being the most popular. Vert.x provides its own implementation. Indeed, using Hystrix can be a bit cumbersome (but possible) as it does not enforce the Vert.x threading model.

In the DashboardVerticle.java file, a circuit breaker (called circuit) is initialized in the start method:

With this circuit breaker, write a callAuditServiceWithExceptionHandlerWithCircuitBreaker method managing the arrival and the departure of the audit service. For this, use the circuit.<Buffer>executeWithFallback method. Don’t forget to update the handler of the /operations route.

Once done, rebuild and restart the dashboard. Stop the audit service and see how it behaves. Restart it. You can see on the dashboard page the state of the circuit breaker.

SockJS is a browser JavaScript library that provides a WebSocket-like object. SockJS gives you a coherent, cross-browser, Javascript API which creates a low latency, full duplex, cross-domain communication channel between the browser and the web server. Under the hood SockJS tries to use native WebSockets first. If that fails it can use a variety of browser-specific transport protocols and presents them through WebSocket-like abstractions. SockJS-client does require a server counterpart to handle the communication. And you know what, Vert.x implements it !

With the SockJS - Event bus bridge, it lets the browser send and receive messages from the event bus.

To enable the bridge you need the following code:

In (1), we create the SockJSHandler. It needs to be configured, as by default, for security reasons, no messages are transmitted. A set of permitted addresses configures bridge (2). Outbound addresses are for messages from the event bus to the browser, while inbound addresses are for messages from the browser to the event bus. Finally in (3) and (4), it configures the handler and create a router in the router. The /eventbus/* path is used by the SockJS client (in the browser) to negotiate the connection, receive and send the messages.

This is not the only bridge that exists for the event bus. There is also a TCP event bus bridge for native systems. Notice also, that the SockJS bridge can also be used from Node.JS.

As said above, there is a bridge between SockJS and the event bus to let the browser send and receive messages. As event bus services communicate using event bus messages, it is possible to implement a service client in the browser. Vert.x generates this client for you.

So, if you open the index.html file, you can see:

This imports a script generated by Vert.x (in the portfolio project). Then we can use the service as follows:

Yes, you can call the service method directly from your browser.