Difficulty: beginner
Estimated Time: 15 minutes

In this scenario, you will learn more about Reactive Microservices using Eclipse Vert.x, one of the runtimes included in Red Hat OpenShift Application Runtimes.

This scenario is the first one in a list of scenarios that will walk you through building a Reactive application using Vert.x illustrating what Vert.x is. These scenarios offer an intermediate, hands-on session with Vert.x, from the first line of code, to making services, to consuming them and finally to assembling everything in a consistent reactive system. It illustrates what reactive systems are, what reactive programming is, and how to build applications based on reactive microservices (and the s is important).

The Micro-Trader Application

The Vert.x application that is being developed is called the Micro-Trader and is composed of multiple microservices as seen below. It is a fake financial app, where we will be making (virtual) money. The application is composed of the following microservices:

  • The quote generator - this is an absolutely unrealistic simulator that generates the quotes for 3 fictional companies MacroHard, Divinator, and Black Coat. The market data is published on the Vert.x event bus. It also publishes an HTTP endpoint to get the current value of the quote.
  • The traders - these are a set of components that receives quotes from the quote generator and decides whether or not to buy or sell a particular share. To make this decision, they rely on another component called the portfolio service.
  • The portfolio - this service manages the number of shares in our portfolio and their monetary value. It is exposed as a service proxy, i.e. an asynchronous RPC service on top of the Vert.x event bus. For every successful operation, it sends a message on the event bus describing the operation. It uses the quote generator to evaluate the current value of the portfolio.
  • The audit - this is to keep a list of all our operations (yes, that’s the law). The audit component receives operations from the portfolio service via an event bus and address. It then stores theses in a database. It also provides a REST endpoint to retrieve the latest set of operations.
  • The dashboard - some UI to let us know when we become rich.

Let’s have a look at the architecture:


The application uses several types of services:

  • HTTP endpoint (i.e. REST API) - this service is located using an HTTP URL.
  • gRPC - gRPC is a secure and fast RPC framework built on top of HTTP/2
  • Message sources - these are components publishing messages on the event bus, the service is located using an (event bus) address.

All the components are going to be deployed in the same Kubernetes namespace (project), and will form a cluster.

The dashboard presents the available services, the value of each company’s quotes, the latest set of operations made by our traders and the current state of our portfolio. It also shows the state of the different circuit breakers.


The first microservice - the quote generator

In this scenario, you are going to create the first microservice - the quote generator. In each subsequent scenario, you will create a microservice (from the set above) that will together form the Micro-Trader Application based on Vert.x.

What is Eclipse Vert.x?

Local Web Browser Tab

If you go on the Vert.x web site, Vert.x is defined as "a toolkit for building reactive applications on the JVM". There are a three important points in this description: toolkit, reactive and "on the JVM"

Firstly, Vert.x is a toolkit. Meaning, Vert.x is not an application server, a container nor a framework. It’s not a JavaScript library either. Vert.x is a plain old jar file, so a Vert.x application is an application that uses this jar file. Vert.x does not define a packaging model, all Vert.x components are plain boring jar files. How does this impact you and your application? Let’s imagine you are using a build tool such as Maven or Gradle, to make your application a Vert.x application just add the vertx-core dependency. Wanna use another Vert.x components, just add it as a dependency. It’s simple, burden-less. Starting the application is a simple class with the public static void main(String[] args) entry point. No specific IDE or plugin to install to start using Vert.x.

Secondly, Vert.x is reactive. It is specifically made to build reactive applications, or more appropriately, systems. Reactive systems [1] has been defined in the Reactive Manifesto. Although, it’s not long document to read, we will further reduce it to these 4 bullet points:

  • Responsive: a reactive system needs to handle requests in a reasonable time (I let you define reasonable).
  • Resilient: a reactive system must stay responsive in the face of failures (crash, timeout, 500 errors…​), so it must be designed for failures and deal with them appropriately.
  • Elastic: a reactive system must stay responsive under various loads. As a consequence, it must scale up and down, and be able to handle the load with minimal resources.
  • Message driven: components from a reactive system interacts using asynchronous message-passing.

Also, Vert.x is event-driven and also non-blocking. Events are delivered in an event loop that must never be blocked. Let’s explain why. Unlike traditional, let’s say "enterprise", systems, Vert.x uses a very small number of threads. Some of these threads are event loops, they are responsible for dispatching the events in Handlers. If you block this thread, the events won’t be delivered anymore. This execution model impacts how you write your code, instead of the traditional model of blocking code, your code is going to be asynchronous and non-blocking.

Finally, Vert.x applications runs "on the JVM" the Java Virtual Machine (8+). This means Vert.x applications can be developed using any language that runs on the JVM. Including Java(of course), Groovy, Ceylon, Ruby, JavaScript, Kotlin and Scala. We can even mix and match any combination of all these languages. The polyglot nature of Vert.x application allows you use the most appropriate language for the task.

Vert.x lets you implement distributed applications, either by using the built-in TCP and HTTP server and client, but also using the Vert.x event bus, a lightweight mechanism to send and receive messages. With the event bus, you send messages to addresses. It supports three modes of distributions:

  1. point to point: the message is sent to a single consumer listening on the address
  2. publish / subscribe: the message is received by all the consumers listening on the address
  3. request / reply: the message is sent to a single consumer and let it reply to the message by sending another message to the initial sender

You might still want to ask: What kind of applications can I use Vert.x for? We say, Vert.x is incredibly flexible - whether it’s simple network utilities, sophisticated modern web applications, HTTP/REST microservices, high volume event processing or a full blown backend message-bus application, Vert.x is a great fit. It’s fast, and does not constraint you. Last but not least, Vert.x provides appropriate tools to build reactive systems; systems that are: responsive, elastic, resilient and asynchronous!


In this scenario, you learned a bit more about what Reactive Systems and Reactive programming are and why it's useful when building Microservices.

  • how projects are structured, built, and deployed

  • how to use the event bus to receive messages

  • how to expose a HTTP endpoint

  • how to use RX Java 2 to avoid callbacks

  • using config maps to configure the application

In the next scenario, , we are going to implement a Portfolio service. A Portfolio stores the owned shares and the available cash.

Eclipse Vert.x on RHOAR

Step 1 of 5

Step 1

The sample project shows the components of a basic Vert.x project laid out in different subdirectories according to Maven best practices.

Examine the Quote Generator project structure.

Switch to the quote-generator project

cd quote-generator

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


|-- README.md 
|-- pom.xml 
|-- src
|   |-- kubernetes/config.json
|   |-- main
|   |   |-- fabric8
|   |   |   `-- deployment.yml 
|   |   |-- java
|   |   |   `-- io/vertx/workshop/quote 
|   |   |               |-- GeneratorConfigVerticle.java
|   |   |               |-- MarketDataVerticle.java
|   |   |               `-- RestQuoteAPIVerticle.java
|   |   `-- solution
|   |       `-- io/vertx/workshop/quote 
|   |                   |-- GeneratorConfigVerticle.java
|   |                   |-- MarketDataVerticle.java
|   |                   `-- RestQuoteAPIVerticle.java
|   `-- test
|       |-- java
|       |   `-- io/vertx/workshop/quote 
|       |               |-- GeneratorConfigVerticleTest.java
|       |               `-- MarketDataVerticleTest.java
|       `-- resources 
`-- target

NOTE: To generate a similar project skeleton you can visit the Vert.x Starter webpage.

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

  1. Define the dependencies
  2. Compile the java code and process resources (if any)
  3. Build a fat-jar

A fat-jar (also called uber jar or shaded jar) is a convenient way to package a Vert.x application. It creates an uber-jar containing your application and all its dependencies, including Vert.x. Then, to launch it, you just need to use java -jar <jar name> without having to handle the CLASSPATH. Vert.x does not dictate a type of packaging. It’s true, fat jars are convenient, but they are not the only way. You can use plain (not fat) jars, OSGi bundles…​ The pom.xml file also contains a set of properties used to configure the application:

  • vertx.verticle defines the main verticle - the entry point
  • vertx.cluster.name defines the name of the cluster
Local Web Browser
OpenShift Console