Note
|
This repository contains the guide documentation source. To view the guide in published form, view it on the Open Liberty website. |
Learn how to write reactive Java microservices using MicroProfile Reactive Messaging.
You will learn how to build reactive microservices that can send requests to other microservices, and asynchronously receive and process the responses. You will use an external messaging system to handle the asynchronous messages that are sent and received between the microservices as streams of events. MicroProfile Reactive Messaging makes it easy to write and configure your application to send, receive, and process the events efficiently.
Asynchronous messaging between microservices
Asynchronous communication between microservices can be used to build reactive and responsive applications. By decoupling the requests sent by a microservice from the responses that it receives, the microservice is not blocked from performing other tasks while waiting for the requested data to become available. Imagine asynchronous communication as a restaurant. A waiter might come to your table and take your order. While you are waiting for your food to be prepared, that waiter serves other tables and takes their orders too. When your food is ready, the waiter brings your food to the table and then continues to serve the other tables. If the waiter were to operate synchronously, they must take your order and then wait until they deliver your food before serving any other tables. In microservices, a request call from a REST client to another microservice can be time-consuming because the network might be slow, or the other service might be overwhelmed with requests and can’t respond quickly. But in an asynchronous system, the microservice sends a request to another microservice and continues to send other calls and to receive and process other responses until it receives a response to the original request.
What is MicroProfile Reactive Messaging?
MicroProfile Reactive Messaging provides an easy way to asynchronously send, receive, and process messages that are received as continuous streams of events. You simply annotate application beans' methods and Open Liberty converts the annotated methods to reactive streams-compatible publishers, subscribers, and processors and connects them up to each other. MicroProfile Reactive Messaging provides a Connector API so that your methods can be connected to external messaging systems that produce and consume the streams of events, such as Apache Kafka.
The application in this guide consists of two microservices, system
and inventory
. Every 15 seconds, the system
microservice calculates and publishes an event that contains its current average system load. The inventory
microservice subscribes to that information so that it can keep an updated list of all the systems and their current system loads. The current inventory of systems can be accessed via the /systems
REST endpoint. You’ll create the system
and inventory
microservices using MicroProfile Reactive Messaging.
You need to have Docker installed. For installation instructions, refer to the official Docker documentation. You will build and run the microservices in Docker containers. An installation of Apache Kafka is provided in another Docker container.
Navigate to the start
directory to begin.
The system
microservice is the producer of the messages that are published to the Kafka messaging system as a stream of events. Every 15 seconds, the system
microservice publishes an event that contains its calculation of the average system load (its CPU usage) for the last minute.
Create theSystemService
class.system/src/main/java/io/openliberty/guides/system/SystemService.java
SystemService.java
link:finish/system/src/main/java/io/openliberty/guides/system/SystemService.java[role=include]
system/microprofile-config.properties
link:finish/system/src/main/resources/META-INF/microprofile-config.properties[role=include]
The SystemService
class contains a Publisher
method that is called sendSystemLoad()
, which calculates and returns the average system load. The @Outgoing
annotation on the sendSystemLoad()
method indicates that the method publishes its calculation as a message on a topic in the Kafka messaging system. The Flowable.interval()
method from rxJava
is used to set the frequency of how often the system service publishes the calculation to the event stream.
The messages are transported between the service and the Kafka messaging system through a channel called systemLoad
. The name of the channel to use is set in the @Outgoing("systemLoad")
annotation. Later in the guide, you will configure the service so that any messages sent by the system
service through the systemLoad
channel are published on a topic called systemLoadTopic
, as shown in the following diagram:
The inventory
microservice records in its inventory the average system load information that it received from potentially multiple instances of the system
service.
Create theInventoryResource
class.inventory/src/main/java/io/openliberty/guides/inventory/InventoryResource.java
InventoryResource.java
link:finish/inventory/src/main/java/io/openliberty/guides/inventory/InventoryResource.java[role=include]
inventory/microprofile-config.properties
link:finish/inventory/src/main/resources/META-INF/microprofile-config.properties[role=include]
The inventory
microservice receives the message from the system
microservice over the @Incoming("systemLoad")
channel. The properties of this channel are defined in the microprofile-config.properties
file. The inventory
microservice is also a RESTful service that is served at the /inventory
endpoint.
The InventoryResource
class contains a method called updateStatus()
, which receives the message that contains the average system load and updates its existing inventory of systems and their average system load. The @Incoming("systemLoad")
annotation on the updateStatus()
method indicates that the method retrieves the average system load information by connecting to the channel called systemLoad
. Later in the guide, you will configure the service so that any messages sent by the system
service through the systemLoad
channel are retrieved from a topic called systemLoadTopic
, as shown in the following diagram:
The system
and inventory
services exchange messages with the external messaging system through a channel. The MicroProfile Reactive Messaging Connector API makes it easy to connect each service to the channel. You just need to add configuration keys in a properties file for each of the services. These configuration keys define properties such as the name of the channel and the topic in the Kafka messaging system. Open Liberty includes the liberty-kafka
connector for sending and receiving messages from Apache Kafka.
The system and inventory microservices each have a MicroProfile Config properties file to define the properties of their outgoing and incoming streams.
Create the system/microprofile-config.properties file.
system/src/main/resources/META-INF/microprofile-config.properties
system/microprofile-config.properties
link:finish/system/src/main/resources/META-INF/microprofile-config.properties[role=include]
inventory/microprofile-config.properties
link:finish/inventory/src/main/resources/META-INF/microprofile-config.properties[role=include]
The mp.messaging.connector.liberty-kafka.bootstrap.servers
property configures the hostname and port for connecting to the Kafka server. The system
microservice uses an outgoing connector to send messages through the systemLoad
channel to the systemLoadTopic
topic in the Kafka message broker so that the inventory
microservices can consume the messages. The key.serializer
and value.serializer
properties characterize how to serialize the messages. The SystemLoadSerializer
class implements the logic for turning a SystemLoad
object into JSON and is configured as the value.serializer
.
The inventory
microservice uses a similar microprofile-config.properties
configuration to define its required incoming stream.
Create the inventory/microprofile-config.properties file.
inventory/src/main/resources/META-INF/microprofile-config.properties
The inventory
microservice uses an incoming connector to receive messages through the systemLoad
channel. The messages were published by the system
microservice to the systemLoadTopic
in the Kafka message broker. The key.deserializer
and value.deserializer
properties define how to deserialize the messages. The SystemLoadDeserializer
class implements the logic for turning JSON into a SystemLoad
object and is configured as the value.deserializer
. The group.id
property defines a unique name for the consumer group. A consumer group is a collection of consumers who share a common identifier for the group. You can also view a consumer group as the various machines that ingest from the Kafka topics. All of these properties are required by the Apache Kafka Producer Configs and Apache Kafka Consumer Configs.
To run the services, the Open Liberty server on which each service runs needs to be correctly configured. Relevant features, including the MicroProfile Reactive Messaging feature, must be enabled for the system
and inventory
services.
Create the system/server.xml configuration file.
system/src/main/liberty/config/server.xml
server.xml
link:finish/system/src/main/liberty/config/server.xml[role=include]
server.xml
link:finish/inventory/src/main/liberty/config/server.xml[role=include]
The server.xml
file is already configured for the inventory
microservice.
Build the system
and inventory
microservices using Maven and then run them in Docker containers.
Create the Maven configuration file.
system/pom.xml
pom.xml
link:finish/system/pom.xml[role=include]
The pom.xml
file lists the microprofile-reactive-messaging-api
, kafka-clients
, and rxjava
dependencies.
The microprofile-reactive-messaging-api
dependency is needed to enable the use of MicroProfile Reactive Messaging API. The kafka-clients
dependency is added because the application needs a Kafka client to connect to the Kafka broker. The rxjava
dependency is used for creating events at regular intervals.
Start your Docker environment. Dockerfiles are provided for you to use.
To build the application, run the Maven install
and package
goals from the command line in the start
directory:
mvn -pl models install
mvn package
Run the following commands to containerize the microservices:
docker build -t system:1.0-SNAPSHOT system/.
docker build -t inventory:1.0-SNAPSHOT inventory/.
Next, use the provided script to start the application in Docker containers. The script creates a network for the containers to communicate with each other. It also creates containers for Kafka, Zookeeper, and the microservices in the project. For simplicity, the script starts one instance of the system service.
./scripts/startContainers.sh
.\scripts\startContainers.bat
After the application is up and running, you can access the application by making a GET request to the /systems
endpoint of the inventory
service.
Go to the http://localhost:9085/inventory/systems URL to access the inventory microservice. You see the CPU systemLoad
property for all the systems:
{
"hostname":"30bec2b63a96",
"systemLoad":2.25927734375
}
You can revisit the http://localhost:9085/inventory/systems URL after a while, and you will notice the CPU systemLoad
property for the systems changed.
You can use the http://localhost:9085/inventory/systems/{hostname}
URL to see the CPU systemLoad
property for one particular system.
In the following example, the 30bec2b63a96
value is the hostname
. If you go to the http://localhost:9085/inventory/systems/30bec2b63a96
URL, you can see the CPU systemLoad
property only for the 30bec2b63a96
hostname
:
{
"hostname":"30bec2b63a96",
"systemLoad":2.25927734375
}
Run the following script to stop the application:
./scripts/stopContainers.sh
.\scripts\stopContainers.bat
You just developed a reactive Java application using MicroProfile Reactive Messaging, Open Liberty, and Kakfa.