Verticle

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.

Understanding the Application

Let's open the GeneratorConfigVerticle class by clicking on the link below and look at the start method

quote-generator/src/main/java/io/vertx/workshop/quote/GeneratorConfigVerticle.java

This method retrieves the configuration, instantiates the verticles and publishes the services in the service discovery.

First, notice the method signature. It receives a Future object indicating that the start is asynchronous. Indeed, all the actions made in this method are asynchronous. So, when the caller thread reaches the end of the method, the actions may have not completed. We use this given Future to indicate when the process has completed (or failed).

The start method:

1. retrieves the configuration (giving the "fake" company settings)
2. deploys one verticle per defined company
3. deploys the RestQuoteAPIVerticle
4. exposes the market-data message source
5. notifies the given Future of the successful completion or failure

As you review the content, you will notice that there are 2 TODO comments. Do not remove them! These comments are used as a marker and without them, you will not be able to finish this scenario.

To retrieve the configuration the verticle needs a ConfigRetriever. This object allows retrieving configuration chunks from different stores (such as git, files, http, etc.). Here we just load the contents of the config.json file located in the src/kubernetes directory. The configuration is a JsonObject. Vert.x uses JSON heavily, so you are going to see a lot of JSON in this lab.

Once we have the retriever, we can retrieve the configuration. This is an asynchronous method (rxGetConfig) returning a Single (a stream containing one item). After the configuration is retrieved, we extract the companies array from it and deploy one verticle per defined company. The deployment is also asynchronous and done with rxDeployVerticle. These company verticles simulate the value of the stocks. The quotes are sent on the event bus on the market address.

Add the below content to the matching // TODO: MarketDataVerticle statement (or use the Copy to Editor button):

.flatMapSingle(company -> vertx.rxDeployVerticle(MarketDataVerticle.class.getName(),
    new DeploymentOptions().setConfig(company)))

When the company verticles are deployed, we deploy another verticle providing an HTTP API to access market data.

Add the below content to the matching // TODO: RestQuoteAPIVerticle statement (or use the Copy to Editor button):

.flatMap(l -> vertx.rxDeployVerticle(RestQuoteAPIVerticle.class.getName()))

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 (a static final variable defined as market) is the event bus address on which the messages are sent.

.flatMap(x -> discovery.rxPublish(MessageSource.createRecord("market-data", ADDRESS)))

Finally, when everything is done, we report the status on the given Future object. The failure management can be made at any stage, but generally, it’s done in the subscribe method:

object.rxAsync(param1, param2)
 // ....
 .subscribe((rec, err) -> {
     if (rec != null) {
         future.complete();
     } else {
         future.fail(err);
     }
 });

If you remember the architecture, the quote generator also provides an HTTP endpoint returning the last values of the quotes. Note that this service is not explicitly published in the service discovery. That’s because Kubernetes is taking care of this part. The Vert.x service discovery interacts with Kubernetes services, so all Kubernetes services can be retrieved by Vert.x

The quote REST endpoint

Open the RestQuoteAPIVerticle. This verticle exposes a HTTP endpoint to retrieve the current / last values of the maker data (quotes). In the start method you need to:

• Receive the event bus market messages to collect the last quotations (in the quotes map)
• Handle HTTP requests to return the list of quotes or a single quote if the name (query) param is set.

In this example we are using streams (Flowable). Streams are an important part of reactive programming and architecture.

Let’s do that…​.

1. Implementing a Handler to receive events

The first action is about observing the stream of market messages. This is done using vertx.eventBus().<JsonObject>consumer(GeneratorConfigVerticle.ADDRESS).toFlowable(). We now have the stream of messages, but we need to extract the JSON body and populate the quotes map. Implement the missing logic that extracts the body of the message (with the body() method), and then put name → quote in the quotes map.

Open the file in the editor:

quote-generator/src/main/java/io/vertx/workshop/quote/RestQuoteAPIVerticle.java

Then, copy the below content to the matching // TODO statements (or use the Copy to Editor button):

Extract the body of the message using .map(msg -> {})

.map(Message::body)  

For each message, populate the quotes map with the received quote. Use .doOnNext(json -> {}) Quotes are json objects you can retrieve from the message body. The map is structured as follows: name -> quote

.doOnNext(json -> {
    quotes.put(json.getString("name"), json); // 2
})

2. Implementing a Handler to handle HTTP requests

Now that you have the quotes, let’s use them to handle HTTP requests. The code already creates the HTTP server and provides the stream of HTTP requests. The stream emits an item for every HTTP request received by the server. So, you need to handle the request and write the response.

Write the content of the request handler to respond to the request:

1. a response with the content-type header set to application/json (already done)
2. retrieve the name parameter (it’s the company name)
3. if the company name is not set, return all the quotes as json.

if the company name is set, return the stored quote or a 404 response if the company is unknown Copy the following to the matching // TODO: Handle the HTTP request statement

String company = request.getParam("name");
if (company == null) {
    String content = Json.encodePrettily(quotes);
    response.end(content);
} else {
    JsonObject quote = quotes.get(company);
    if (quote == null) {
        response.setStatusCode(404).end();
    } else {
        response.end(quote.encodePrettily());
    }
}

1. Get the response object from the request
2. Gets the name parameter (query parameter)
3. Encode the map to JSON
4. Write the response and flush it using end(…​)
5. If the given name does not match a company, set the status code to 404

You may wonder why synchronization is not required. Indeed we write in the map and read from it without any synchronization constructs. Here is one of the main feature of Vert.x: all this code is going to be executed by the same event loop, so it’s always accessed by the same thread, never concurrently.

You have seen the basics of Vert.x development including Asynchronous API and AsyncResult, implementing Handler and receiving messages from the event bus

In next step of this scenario we will deploy our application to the OpenShift Container Platform.

Red Hat OpenShift Container Platform

Red Hat OpenShift Container Platform is the preferred runtime for the Red Hat OpenShift Application Runtimes like Vert.x. OpenShift Container Platform is based on Kubernetes which is probably the most used Orchestration for containers running in production. OpenShift is currently the only container platform based on Kuberenetes that offers multitenancy. This means that developers can have their own personal, isolated projects to test and verify application before committing to a shared code repository.

OpenShift also ships with a feature rich web console as well as command line tools to provide users with a friendly interface to work with applications deployed to the platform.

1. Login to OpenShift Container Platform

Do this in the 1st terminal. To login, we will use the oc command and then specify username and password like this:

oc login https://[[HOST_SUBDOMAIN]]-8443-[[KATACODA_HOST]].environments.katacoda.com -u developer -p developer --insecure-skip-tls-verify=true

Congratulations, you are now authenticated to the OpenShift server.

IMPORTANT: If the above oc login command doesn't seem to do anything, you may have forgotten to stop the application from the previous step. Click on the terminal and press CTRL-C to stop the application and try the above oc login command again!

2. Create project

Projects are a top-level concept to help you organize your deployments. An OpenShift project allows a community of users (or a user) to organize and manage their content in isolation from other communities. Each project has its own resources, policies (who can or cannot perform actions), and constraints (quotas and limits on resources, etc.). Projects act as a wrapper around all the application services and endpoints you (or your teams) are using for your work.

For this scenario, let's create a project that you will use to house your applications.

oc new-project vertx-kubernetes-workshop

oc policy add-role-to-group edit system:serviceaccounts -n vertx-kubernetes-workshop

The first instruction creates the project. The second instruction grants permissions in order to use all the OpenShift capabilities.

3. Open the OpenShift Web Console

OpenShift ships with a web-based console that will allow users to perform various tasks via a browser. To get a feel for how the web console works, click on the "OpenShift Console" tab next to the "Local Web Browser" tab.

You should see the newly created project. Click on it. It’s empty, so let’s deploy our first application.

Deploy to OpenShift

Now that you've logged into OpenShift, let's deploy our new micro-trader Vert.x microservice:

1. Create a ConfigMap

A config map is a Kubernetes entity storing the configuration of an application. The application configuration is in src/kubernetes/config.json. We are going to create a config map from this file. In a terminal, execute:

oc create configmap app-config --from-file=src/kubernetes/config.json

To check that the config map has been created correctly, execute:

oc get configmap -o yaml

It should display the Kubernetes entity and in the data entry our json content.

Now that the config map is created, let’s read it from our application. There are several ways to consume a config map:

• ENV variables
• Config mounted as a file
• Vert.x Config

We are going to use the second approach and mount the configuration as a file in the application container. Indeed, our application has been configured to read its configuration from a src/kubernetes/config.json file:

private ConfigRetrieverOptions getConfigurationOptions() {
    JsonObject path = new JsonObject().put("path", "src/kubernetes/config.json");
    return new ConfigRetrieverOptions().addStore(new ConfigStoreOptions().setType("file").setConfig(path));
}

For that, we have defined additional config in quote-generator/src/main/fabric8/deployment.yml{{open} that contains the right configuration to:

1. define a volume with the config map content
2. mount this volume in the right directory

You can also see that this file contains the JAVA options we pass to the process.

2. Start the quote generator

Red Hat OpenShift Application Runtimes includes a powerful maven plugin that can take an existing Eclipse Vert.x application and generate the necessary Kubernetes configuration.

Build and deploy the project using the following command, which will use the maven plugin to deploy:

mvn fabric8:deploy

The build and deploy may take a minute or two. Wait for it to complete. You should see a BUILD SUCCESS at the end of the build output.

After the maven build finishes it will take less than a minute for the application to become available. To verify that everything is started, run the following command and wait for it complete successfully:

oc rollout status -w dc/quote-generator

3. Access the application running on OpenShift

Click on the route URL to access the sample UI.

You can also access the application through the link for the quote-generator route on the OpenShift Web Console Overview page.

You should now see an HTML page that looks like this:

{
  "MacroHard" : {
    "volume" : 100000,
    "shares" : 51351,
    "symbol" : "MCH",
    "name" : "MacroHard",
    "ask" : 655.0,
    "bid" : 666.0,
    "open" : 600.0
  },
  "Black Coat" : {
    "volume" : 90000,
    "shares" : 45889,
    "symbol" : "BCT",
    "name" : "Black Coat",
    "ask" : 654.0,
    "bid" : 641.0,
    "open" : 300.0
  },
  "Divinator" : {
    "volume" : 500000,
    "shares" : 251415,
    "symbol" : "DVN",
    "name" : "Divinator",
    "ask" : 877.0,
    "bid" : 868.0,
    "open" : 800.0
  }
}

4. Build and Deploy the micro-trader-dashboard

cd /root/code/micro-trader-dashboard

mvn fabric8:deploy

In the OpenShift web console, wait until the pod is ready and click on the associated route. Append "/admin" at the end of the URL and you should see the dashboard. If you go into the trader tab, the graph should display the evolution of the market.

Alternatively, you can click on the route URL to access the sample UI.

5. You are not a financial expert ? 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:

• name : the company name

• symbol : short name

• shares : the number of stock that can be bought

• open : the stock price when the session opened

• ask : the price of the stock when you buy them (seller price)

• bid : the price of the stock when you sell them (buyer price)

You can check Wikipedia for more details.

Congratulations!

You have deployed the quote-generator as a microservice. In the next component, we are going to implement an event bus service (the portfolio microservice).