<commit_before>## Event bus services - Portfolio service

In the quote generator we have seen the basics of Vert.x development:

* Asynchronous API and `AsyncResult`
* Implementing `Handler`
* Receiving messages from the event bus

In the portfolio component, we are going to implement an _event bus service_. A `Portfolio` stores the owned shares and
the available cash.

### RPC and Async RPC

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:

[plantuml, rpc-sequence, png]
----
@startuml
autonumber
Bob -> Proxy: hello("Bob")
hnote over Bob : blocked
Proxy -> Proxy: Encapsulate the call in a network message
Proxy ->o Server: Network Communication
Server -> Server: Unpack the message
Server -> Alice: hello("Bob")
Server -> Server: Encapsulate the result in a network message
Server ->o Proxy: Network Communication
Proxy -> Proxy: Unpack the message
Proxy -> Bob : "hello Bob"
@enduml
----

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:

1. how the service is called
2. where the service is living (location)

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.

[plantuml, async-rpc-sequence, png]
----
 @startuml
 autonumber
 participant Bob
 participant Handler
 participant Proxy
 participant Server
 participant Alice
 Bob -> Proxy: hello("Bob", handler)
 hnote over Bob : not blocked
 Proxy -> Proxy: Encapsulate the call in a network message
 Proxy ->o Server: Network Communication (event bus message)
 Server -> Server: Unpack the message
 Server -> Alice: hello("Bob")
 Server -> Server: Encapsulate the result in a network message
 Server ->o Proxy: Network Communication (event bus message reply)
 Proxy -> Proxy: Unpack the message
 Proxy -> Handler : AsyncResult("hello Bob")
 @enduml
----

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:

* the caller is not blocked
* it deals with failures
* it avoids you to send messages on the event bus and manages object marshalling and unmarshalling for you.

### Async service interface

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:

* `ProxyGen` - enables the event bus service proxy and server generation
* `VertxGen`  - enables the creation of the proxy in the different language supported by Vert.x

Let's have a look at the first method:

[source]
----
void getPortfolio(Handler<AsyncResult<Portfolio>> resultHandler);
----

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.

NOTE: You may have also noticed that the package has a `package-info.java` file. This file is required to enable the
service proxy generation.

=== Data objects

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 http://vertx.io/docs/vertx-service-proxy/java/[documentation] for the whole list
 of supported types). Data objects are Java classes obeying to a set of constraints:

* It must be annotated with `DataObject`
* It must have an empty constructor, a copy constructor and a constructor taking a `JsonObject` as parameter
* It must have a `toJson` method building a `JsonObject` representing the current object
* Fields must be _property_ with (getters and setters)

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_.

=== Implementing the service

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:

* `getPortfolio` to understand how to create `AsyncResult` objects
* `sendActionOnTheEventBus` to see how to send messages on the event bus
* `evaluate` computing the current value of the portfolio

==== Task - Creating AsyncResult instances

As we have seen above, our async service have `Handler<AsyncResult<Portfolio>>` parameter. So when we implement this
service, we would need to call the `Handler` with an instance of `AsyncResult`. To see how this works, let's
implement the `getPortfolio` method:

In `io.vertx.workshop.portfolio.impl.PortfolioServiceImpl`, fill the `getPortfolio` method. It should call the `handle` method of the `resultHandler` with a _successful_ async result. This object can be created from the (Vert.x) `Future` method.

****
[.assignment]
[source, java]
----
resultHandler.handle(Future.succeededFuture(portfolio));
----

Wow... one single line ? Let's dissect it:

* `resultHandler.handle` : this is to invoke the `Handler`. `Handler<X>` has a single method (`handle(X)`).
* `Future.succeededFuture` : this is how we create an instance of `AsyncResult` denoting a success. The passed value
 is the result (`portfolio`)
****

But, wait, what is the relationship between `AsyncResult` and `Future` ? A `Future` represents the result of an action
that may, or may not, have occurred yet. The result may be `null` if the `Future` is used to detect the completion of
 an operation. The operation behind a `Future` object may succeed or fail. `AsyncResult` is a structure describing the
  success of the failure of an operation. So, `Future` are `AsyncResult`. In Vert.x `AsyncResult` instances are
  created from the `Future` class.

`AsyncResult` describes:

* a success as shown before, it encapsulates the result
* a failure, it encapsulates a `Throwable` instance

NOTE: Did you know that the term `Future` has been introduced in 1977, `Promise` in 1976... Not really new things.

So, how does this work with our async RPC service, let's look at this sequence diagram:

[plantuml, portfolio-sequence, png]
----
 @startuml
 autonumber
 participant user
 participant handler
 participant proxy
 user -> proxy: proxy.getPorfolio(handler)
 proxy -> proxy: Encapsulate the call in a network message
 proxy ->o server: Network Communication (event bus message)
 server -> server: Unpack the message
 server -> PortfolioServiceImpl_instance: getPortfolio(another-handler)
 PortfolioServiceImpl_instance -> PortfolioServiceImpl_instance: another-handler.handle(Future.succeededFuture(portfolio));
 server -> server : Encapsulate the result in a network message
 server ->o proxy: Network Communication (event bus message reply)
 proxy -> proxy: Unpack the message
 proxy -> handler : resultHandler.handle(Future.succeededFuture(portfolio))
 @enduml
----

==== Task - Sending event on the event bus

In the previous chapter, we have registered a consumer receiving event bus services, it's time to see how to send
messages on the event bus. You access the event bus using `vertx.eventBus()`. From this object you can:

* `send` : send a message in point to point mode
* `publish` : broadcast a message to all consumers registered on the address
* `send` with a `Handler<AsyncResult<Message>>>`: send a message in point to point mode and expect a reply

In the last point, notice the `AsyncResult<Message>`. It's an async result as the reply may never arrive (and so will
 be considered as a failure).

Ok, back to our code. We have provided the `buy` and `sell` methods, that are just doing some checks before buying or
 selling shares. Once the action is _emitted_, we send a message on the event bus that will be consumed by the `Audit
  Service` and the `Dashboard`. So, we are going to use the `publish` method.

Write the body of the `sendActionOnTheEventBus` method in order to publish a message on the `EVENT_ADDRESS` address containing a `JsonObject` as body. This object must contains the following entries:

* action -> the action (buy or sell)
* quote -> the quote as Json
* date -> a date (long in milliseconds)
* amount -> the amount
* owned -> the updated (owned) amount

[.assignment]
****
[source, java]
----
vertx.eventBus().publish(EVENT_ADDRESS, new JsonObject()
    .put("action", action)
    .put("quote", quote)
    .put("date", System.currentTimeMillis())
    .put("amount", amount)
    .put("owned", newAmount));
----

Let's have a deeper look:

1. it gets the `EventBus` instance and call `publish` on it. The first parameter is the _address_ on which the
message is sent
2. the body is a `JsonObject` containing the different information on the action (buy or sell, the quote (another
json object), the date...
****

==== Task - Coordinating async methods and consuming HTTP endpoints - Portfolio value evaluation

The last method to implement is the `evaluate` method. This method computes the current value of the portfolio.
However, for this it needs to access the "current" value of the stock (so the last quote). It is going to consume
the HTTP endpoint we have implemented in the quote generator. For this, we are going to:

* discover the service
* call the service for each company we own some shares
* when all calls are done, compute the value and send it back to the caller

That's a bit more tricky, so let's do it step by step. First, in the `evaluate`, we need to retrieve the HTTP
endpoint (service) provided by the quote generator. This service is named `quotes`. We published in in the previous
section. So, let's start to get this service.

Fill the `evaluate` method to retrieve the `quotes` service. You can retrieve Http services using `HttpEndpoint.getClient`. The `name` of the service is `quotes`. If you can't retrieve the service, just passed a failed async result to the handler. Otherwise, call `computeEvaluation`.

[.assignment]
****
[source, java]
----<commit_msg>Portfolio docfix: HttpEndpoint Web Client<commit_after>## Event bus services - Portfolio service

In the quote generator we have seen the basics of Vert.x development:

* Asynchronous API and `AsyncResult`
* Implementing `Handler`
* Receiving messages from the event bus

In the portfolio component, we are going to implement an _event bus service_. A `Portfolio` stores the owned shares and
the available cash.

### RPC and Async RPC

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:

[plantuml, rpc-sequence, png]
----
@startuml
autonumber
Bob -> Proxy: hello("Bob")
hnote over Bob : blocked
Proxy -> Proxy: Encapsulate the call in a network message
Proxy ->o Server: Network Communication
Server -> Server: Unpack the message
Server -> Alice: hello("Bob")
Server -> Server: Encapsulate the result in a network message
Server ->o Proxy: Network Communication
Proxy -> Proxy: Unpack the message
Proxy -> Bob : "hello Bob"
@enduml
----

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:

1. how the service is called
2. where the service is living (location)

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.

[plantuml, async-rpc-sequence, png]
----
 @startuml
 autonumber
 participant Bob
 participant Handler
 participant Proxy
 participant Server
 participant Alice
 Bob -> Proxy: hello("Bob", handler)
 hnote over Bob : not blocked
 Proxy -> Proxy: Encapsulate the call in a network message
 Proxy ->o Server: Network Communication (event bus message)
 Server -> Server: Unpack the message
 Server -> Alice: hello("Bob")
 Server -> Server: Encapsulate the result in a network message
 Server ->o Proxy: Network Communication (event bus message reply)
 Proxy -> Proxy: Unpack the message
 Proxy -> Handler : AsyncResult("hello Bob")
 @enduml
----

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:

* the caller is not blocked
* it deals with failures
* it avoids you to send messages on the event bus and manages object marshalling and unmarshalling for you.

### Async service interface

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:

* `ProxyGen` - enables the event bus service proxy and server generation
* `VertxGen`  - enables the creation of the proxy in the different language supported by Vert.x

Let's have a look at the first method:

[source]
----
void getPortfolio(Handler<AsyncResult<Portfolio>> resultHandler);
----

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.

NOTE: You may have also noticed that the package has a `package-info.java` file. This file is required to enable the
service proxy generation.

=== Data objects

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 http://vertx.io/docs/vertx-service-proxy/java/[documentation] for the whole list
 of supported types). Data objects are Java classes obeying to a set of constraints:

* It must be annotated with `DataObject`
* It must have an empty constructor, a copy constructor and a constructor taking a `JsonObject` as parameter
* It must have a `toJson` method building a `JsonObject` representing the current object
* Fields must be _property_ with (getters and setters)

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_.

=== Implementing the service

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:

* `getPortfolio` to understand how to create `AsyncResult` objects
* `sendActionOnTheEventBus` to see how to send messages on the event bus
* `evaluate` computing the current value of the portfolio

==== Task - Creating AsyncResult instances

As we have seen above, our async service have `Handler<AsyncResult<Portfolio>>` parameter. So when we implement this
service, we would need to call the `Handler` with an instance of `AsyncResult`. To see how this works, let's
implement the `getPortfolio` method:

In `io.vertx.workshop.portfolio.impl.PortfolioServiceImpl`, fill the `getPortfolio` method. It should call the `handle` method of the `resultHandler` with a _successful_ async result. This object can be created from the (Vert.x) `Future` method.

****
[.assignment]
[source, java]
----
resultHandler.handle(Future.succeededFuture(portfolio));
----

Wow... one single line ? Let's dissect it:

* `resultHandler.handle` : this is to invoke the `Handler`. `Handler<X>` has a single method (`handle(X)`).
* `Future.succeededFuture` : this is how we create an instance of `AsyncResult` denoting a success. The passed value
 is the result (`portfolio`)
****

But, wait, what is the relationship between `AsyncResult` and `Future` ? A `Future` represents the result of an action
that may, or may not, have occurred yet. The result may be `null` if the `Future` is used to detect the completion of
 an operation. The operation behind a `Future` object may succeed or fail. `AsyncResult` is a structure describing the
  success of the failure of an operation. So, `Future` are `AsyncResult`. In Vert.x `AsyncResult` instances are
  created from the `Future` class.

`AsyncResult` describes:

* a success as shown before, it encapsulates the result
* a failure, it encapsulates a `Throwable` instance

NOTE: Did you know that the term `Future` has been introduced in 1977, `Promise` in 1976... Not really new things.

So, how does this work with our async RPC service, let's look at this sequence diagram:

[plantuml, portfolio-sequence, png]
----
 @startuml
 autonumber
 participant user
 participant handler
 participant proxy
 user -> proxy: proxy.getPorfolio(handler)
 proxy -> proxy: Encapsulate the call in a network message
 proxy ->o server: Network Communication (event bus message)
 server -> server: Unpack the message
 server -> PortfolioServiceImpl_instance: getPortfolio(another-handler)
 PortfolioServiceImpl_instance -> PortfolioServiceImpl_instance: another-handler.handle(Future.succeededFuture(portfolio));
 server -> server : Encapsulate the result in a network message
 server ->o proxy: Network Communication (event bus message reply)
 proxy -> proxy: Unpack the message
 proxy -> handler : resultHandler.handle(Future.succeededFuture(portfolio))
 @enduml
----

==== Task - Sending event on the event bus

In the previous chapter, we have registered a consumer receiving event bus services, it's time to see how to send
messages on the event bus. You access the event bus using `vertx.eventBus()`. From this object you can:

* `send` : send a message in point to point mode
* `publish` : broadcast a message to all consumers registered on the address
* `send` with a `Handler<AsyncResult<Message>>>`: send a message in point to point mode and expect a reply

In the last point, notice the `AsyncResult<Message>`. It's an async result as the reply may never arrive (and so will
 be considered as a failure).

Ok, back to our code. We have provided the `buy` and `sell` methods, that are just doing some checks before buying or
 selling shares. Once the action is _emitted_, we send a message on the event bus that will be consumed by the `Audit
  Service` and the `Dashboard`. So, we are going to use the `publish` method.

Write the body of the `sendActionOnTheEventBus` method in order to publish a message on the `EVENT_ADDRESS` address containing a `JsonObject` as body. This object must contains the following entries:

* action -> the action (buy or sell)
* quote -> the quote as Json
* date -> a date (long in milliseconds)
* amount -> the amount
* owned -> the updated (owned) amount

[.assignment]
****
[source, java]
----
vertx.eventBus().publish(EVENT_ADDRESS, new JsonObject()
    .put("action", action)
    .put("quote", quote)
    .put("date", System.currentTimeMillis())
    .put("amount", amount)
    .put("owned", newAmount));
----

Let's have a deeper look:

1. it gets the `EventBus` instance and call `publish` on it. The first parameter is the _address_ on which the
message is sent
2. the body is a `JsonObject` containing the different information on the action (buy or sell, the quote (another
json object), the date...
****

==== Task - Coordinating async methods and consuming HTTP endpoints - Portfolio value evaluation

The last method to implement is the `evaluate` method. This method computes the current value of the portfolio.
However, for this it needs to access the "current" value of the stock (so the last quote). It is going to consume
the HTTP endpoint we have implemented in the quote generator. For this, we are going to:

* discover the service
* call the service for each company we own some shares
* when all calls are done, compute the value and send it back to the caller

That's a bit more tricky, so let's do it step by step. First, in the `evaluate`, we need to retrieve the HTTP
endpoint (service) provided by the quote generator. This service is named `quotes`. We published in in the previous
section. So, let's start to get this service.

Fill the `evaluate` method to retrieve the `quotes` service. You can retrieve Http services using `HttpEndpoint.getWebClient`.
The `name` of the service is `quotes`. If you can't retrieve the service, just pass a failed async result to the handler. Otherwise, call `computeEvaluation`.

[.assignment]
****
[source, java]
----
{'fraction_non_alphanumeric': 0.07415031334339692, 'fraction_numerical': 0.0010978454782489364, 'mean_word_length': 4.431552795031056, 'pattern_counts': {'":': 0, '<': 25, '<?xml version=': 0, '>': 91, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2201230', 'n_tokens_mistral': 5789, 'n_tokens_neox': 5570, 'n_words': 3106}