Todo-list Tutorial

This is the most straightforward Hello World type of application with Event Sourcing and CQRS on top of light-eventuate-4j. It has command side service that adds a new todo item, updates an existing todo item and removes a todo item. It also has query side service to retrieve all the todo items for display in a single page application.

This example can be found at light-example-4j.

There are five parts in this projects:

  • Common module defines domain object and event object across modules on both command side and query side

  • Command side API implemented on top of light-eventuate-4j to build and publish events.

  • Command side microservice (Restful based or hybrid based) to trigger command API

  • Query side API implemented on top of light-eventuate-4j to define the event handlers and subscribe events and process by specified event handlers.

  • Query side microservice (Restful based or hybrid based) to trigger query API.

Process Flow

drawing5

Step 1: Application or browser sends restful HTTP post request to command service to create a todo

Step 2: Command service processes the request and generates a “create todo” event; And then publishes the event to the event store

Step 3: CDC service will capture the data change based on MySQL replication log and publish the event data to Kafka distributed stream system

Step 4: Query side service’s event handler knows the new event data published to Kafka, an event handler will subscribe to the event

Step 5: Query side service will process the event and save the result to a local table. (In this example: mysql/todo_db/TODO)

Step 6: Application or browser sends restful HTTP GET request to query service to get ALL todo list

Step 7: Query side service processes the request and gets the todo list from local table

Step 8: Query side service returns the HTTP response to the consumer.

Steps

The following steps will assume you know the basics about light-eventuate-4j as well as light-rest-4j and light-hybrid-4j as we are going to build services in both RESTful style and Hybrid RPC style.

Before starting any service, we need to make sure that light-eventuate-4j is up and running. Please follow this getting started to set up.

We are going to implement the application in both light-rest-4j and light-hybrid-4, and the two implementations will be sitting in the same folders in light-example-4j.

As the todo-list folder already in the public repository of light-example-4j/eventuate, we are going to rename the existing project so that you can compare these folders if you want.

Here are all steps in this tutorial and it is the best to follow them in sequence.

Prepare Environment

Assuming that light-eventuate-4j platform is up and running, let’s check out the light-example-4j project and rename the todo-list folder in eventuate so that we can recreate it in this tutorial. As with other tutorials, we are going to use networknt under user’s home directory as our workspace. The default configuration in the source code uses remote Kafka and MySQL hosted in the cloud for developers. We encourage you to set up your own eventuate environment locally once you feel comfortable so that you can learn the process. Read More »

Multi-Module Project

As we have made a backup of the existing todo-list applications, we are going to create a new folder and copy some of the files or directories to the new folder. At any time, you can always compare the two folders to find out the differences. Let’s create a todo-list folder and copy the pom.xml from the existing project. cd ~/networknt/light-example-4j/eventuate mkdir todo-list cd todo-list cp ../todo-list.bak/pom.xml . Now let’s copy common, command and query modules to the todo-list folder from existing one. Read More »

Rest Command Side

In this step, we are going to generate a command side restful microservice from scratch. The model-config for this service can be found at model-config repo. Let’s first checkout model-config repo from GitHub. git clone [email protected]:networknt/model-config.git The swagger specification for the todo-list command side service can be found at ~/networknt/model-config/rest/todo-command. In the same folder, there is config.json which is used to control how light-codegen going to generate the code. In order to generate the rest-command service, let’s first clone the light-codegen project and build it. Read More »

Hybrid Docker

Copy service jar files to the service folder in light-docker: For hybrid command service : cd ~/networknt/light-docker/eventuate/hybrid-command/service cp ~/networknt/light-example-4j/eventuate/todo-list/common/target/todo-common-0.1.0.jar . cp ~/networknt/light-example-4j/eventuate/todo-list/command/target/todo-command-0.1.0.jar . cp ~/networknt/light-example-4j/eventuate/todo-list/hybrid-command/target/hybrid-command-0.1.0.jar . cp ~/networknt/light-eventuate-4j/hybrid-command/target/hybrid-command-1.0.0.jar . For hybrid query: cd ~/networknt/light-docker/eventuate/hybrid-query/service cp ~/networknt/light-example-4j/eventuate/todo-list/common/target/todo-common-0.1.0.jar . cp ~/networknt/light-example-4j/eventuate/todo-list/command/target/todo-command-0.1.0.jar . cp ~/networknt/light-example-4j/eventuate/todo-list/query/target/todo-query-0.1.0.jar . cp ~/networknt/light-example-4j/eventuate/todo-list/hybrid-query/target/hybrid-query-0.1.0.jar . cp ~/networknt/light-eventuate-4j/hybrid-query/target/hybrid-query-1.0.0.jar . Go to light-docker root folder and start docker-compose file for eventutate hybrid service: cd ~/networknt/light-docker/ docker-compose -f docker-compose-eventuate-hybrid-local.yml up Verify result with following commands. Read More »

Rest Docker

Let’s copy docker config folder to the todo-list folder from the existing one. cd ~/networknt/light-example-4j/eventuate/todo-list cp -r ../todo-list.bak/docker . There are two sub-folders in the docker module: command-service Since the service runs in the docker container, we need to change the MySQL hostname to use docker image name: service.yml: - javax.sql.DataSource:- com.zaxxer.hikari.HikariDataSource:DriverClassName:com.mysql.jdbc.DriverjdbcUrl:jdbc:mysql://mysql:3306/eventuate?useSSL=falseusername:mysqluserpassword:mysqlpwTo create and publish the rest-command docker image. ./build.sh 1.5.13 query-service Since the service runs in the docker container, we need to change the MySQL hostname and Kafka hostname to use docker image name: Read More »

Hybrid Services Test

We will start hybrid-command server and hybrid-query server manually first and then start them together along with services in a docker-compose. The first step is to make sure light-eventuate-4j platform is up and running. Please follow this tutorial To start hybrid servers manually, we need to check out light-eventuate-4j as these two servers are part of it. cd ~/networknt git clone https://github.com/networknt/light-eventuate-4j.git git clone https://github.com/networknt/light-docker.git cd light-eventuate-4j mvn clean install Next, let’s start hybrid-command server with cdc-service and todo-list hybrid-command service. Read More »

Rest Services Test

Once all modules can be built successfully, we can start the servers and test the todo-list application. First, we need to make sure Mysql, Zookeeper, Kafka and CDC server for eventuate are up and running. You can follow this tutorial to start all of them with a docker-compose. Before we start the rest-command and rest-query, let’s create the database and table for the rest-query material view in the same Mysql database for the event store. Read More »

Hybrid Query

To create a query side hybrid service, we are going to use light-codegen to generate the project in the todo-list. Before generating the project, we need to create a config.json to control how the generator works and a schema.json to define the service contract. These two files can be found in model-config/hybrid/todo-query folder. config.json { "rootPackage": "com.networknt.todolist.query", "handlerPackage":"com.networknt.todolist.query.handler", "modelPackage":"com.networknt.todolist.query.model", "artifactId": "hybrid-query", "groupId": "com.networknt", "name": "hybrid-query", "version": "0.1.0", "overwriteHandler": true, "overwriteHandlerTest": true, "httpPort": 8082, "enableHttp": true, "httpsPort": 8443, "enableHttps": false, "enableRegistry": false, "supportOracle": false, "supportMysql": false, "supportPostgresql": false, "supportH2ForTest": false, "supportClient": false, "dockerOrganization": "networknt" } schema. Read More »

Hybrid Command

So far, we have tried to implement both Command and Query services with Restful APIs. From this step, we are going to implement these service with the light-hybrid-4j framework. Although we can put cdc-service, hybrid-command, hybrid-query into the same hybrid server instance, we are going to use two hybrid server instances to showcase Command Query Responsibility Segregation(CQRS). If we use the hybrid framework, we don’t need the RESTful CDC service anymore. Read More »

Rest Query Side

The swagger specification for the todo-list query side service can be found at ~/networknt/model-config/rest/todo-query. In the same folder, there is config.json which is used to control how light-codegen is going to generate the code. Generate rest-query service with the following command line. Assume we are still in light-codegen folder. java -jar codegen-cli/target/codegen-cli.jar -f swagger -o ../light-example-4j/eventuate/todo-list/rest-query -m ../model-config/rest/todo_query/1.0.0/swagger.json -c ../model-config/rest/todo_query/1.0.0/config.json Now add this rest-query into parent pom.xml and build it with maven. Read More »