The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.

Using Kogito to add rule engine capabilities to an application

This guide demonstrates how your Quarkus application can use Kogito to add DRL files with rules.

Kogito is a next generation business automation toolkit that originates from well known Open Source projects Drools (for business rules) and jBPM (for business processes). Kogito aims at providing another approach to business automation where the main message is to expose your business knowledge (processes, rules and decisions) in a domain specific way.

Prerequisites

要完成这个指南,你需要:

  • 大概15分钟

  • 编辑器

  • 安装JDK 11以上版本并正确配置了 JAVA_HOME

  • Apache Maven 3.8.1+

  • A working container runtime (Docker or Podman)

  • 如果你愿意的话,还可以选择使用Quarkus CLI

  • 如果你想构建原生可执行程序,可以选择安装Mandrel或者GraalVM,并正确配置(或者使用Docker在容器中进行构建)

Architecture

In this example, we build a very simple microservice which offers one REST endpoint:

  • /find-approved

This endpoint will be automatically generated based on the query inserted in the Rule Unit of the DRL file. It’s an example of a stateless invocation (also called "pure function invocation") in which the execution of our business rules doesn’t have any side effects. The output value returned is based uniquely on the input provided.

Business rule

A business rule allows to externalise decision logic into reusable pieces that can be easily used in declarative way. There are multiple ways of writing rules like DMN models, decision tables, decision trees, rules, etc. For this example we focus on the rule format backed by DRL (Drools Rule Language).

Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the complete example.

Clone the Git repository: git clone https://github.com/quarkusio/quarkus-quickstarts.git, or download an archive.

The solution is located in the kogito-drl-quickstart directory.

Creating the Maven Project

First, we need a new project. Create a new project with the following command:

CLI
quarkus create app org.acme:kogito-drl-quickstart \
    --extension=kogito-quarkus-rules,resteasy-reactive-jackson \
    --no-code
cd kogito-drl-quickstart

创建Grade项目,请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

关于如何安装并使用Quarkus CLI的更多信息,请参考Quarkus CLI指南

Maven
mvn io.quarkus.platform:quarkus-maven-plugin:2.11.2.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=kogito-drl-quickstart \
    -Dextensions="kogito-quarkus-rules,resteasy-reactive-jackson" \
    -DnoCode
cd kogito-drl-quickstart

创建Grade项目,请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

This command generates a Maven project, importing the kogito-quarkus-rules extension that comes with all needed dependencies and configuration to equip your application with business automation. It also imports the resteasy-reactive-jackson extension that is needed for Kogito to expose REST services.

If you already have your Quarkus project configured, you can add the kogito-quarkus-rules extension to your project by running the following command in your project base directory:

CLI
quarkus extension add 'kogito-quarkus-rules'
Maven
./mvnw quarkus:add-extension -Dextensions="kogito-quarkus-rules"
Gradle
./gradlew addExtension --extensions="kogito-quarkus-rules"

This will add the following to your build file:

pom.xml
<dependency>
    <groupId>org.kie.kogito</groupId>
    <artifactId>kogito-quarkus-rules</artifactId>
</dependency>
build.gradle
implementation("org.kie.kogito:kogito-quarkus-rules")

Writing the application

Let’s start from the application domain model. This application will approve Loan Applications, so we have a class with all the details of the wanted Loan:

package org.acme.kogito.model;

public class LoanApplication {

   private String id;
   private Applicant applicant;
   private int amount;
   private int deposit;
   private boolean approved = false;

   public LoanApplication() {

   }

   public LoanApplication(String id, Applicant applicant,
                      	int amount, int deposit) {
       this.id = id;
       this.applicant = applicant;
       this.amount = amount;
       this.deposit = deposit;
   }

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }

    public Applicant getApplicant() {
        return applicant;
    }

    public void setApplicant(Applicant applicant) {
        this.applicant = applicant;
    }

    public int getAmount() {
        return amount;
    }

    public void setAmount(int amount) {
        this.amount = amount;
    }

    public int getDeposit() {
        return deposit;
    }

    public void setDeposit(int deposit) {
        this.deposit = deposit;
    }

    public boolean isApproved() {
        return approved;
    }

    public void setApproved(boolean approved) {
        this.approved = approved;
    }
}

And another class with the details of the Applicant:

package org.acme.kogito.model;

public class Applicant {

   private String name;
   private int age;

   public Applicant() {
   }

   public Applicant(String name, int age) {
       this.name = name;
       this.age = age;
   }

   public String getName() {
       return name;
   }

   public void setName(String name) {
       this.name = name;
   }

   public int getAge() {
       return age;
   }

   public void setAge(int age) {
       this.age = age;
   }
}

Next, we create a rule file loan-rules.drl inside the src/main/resources/org/acme/kogito/queries folder of the generated project.

package org.acme.kogito.queries;

unit LoanUnit; // no need to using globals, all variables and facts are stored in the rule unit

import org.acme.kogito.model.Applicant;
import org.acme.kogito.model.LoanApplication;

rule LargeDepositApprove when
   $l: /loanApplications[ applicant.age >= 20, deposit >= 1000, amount <= maxAmount ] // oopath style
then
   modify($l) { setApproved(true) };
end

rule LargeDepositReject when
   $l: /loanApplications[ applicant.age >= 20, deposit >= 1000, amount > maxAmount ]
then
   modify($l) { setApproved(false) };
end

// ... more loans approval/rejections business rules ...

// approved loan applications are now retrieved through a query
query FindApproved
   $l: /loanApplications[ approved ]
end

In this file there are some example rules to decide whether the Loan should be approved or not. The service wants the Applicant to have an age equal or greater than 20 and more than 1000 currency on their bank account. The amount of the Loan shouldn’t be more than the maxAmount.

This example uses Rule Units, a new concept introduced in Kogito that helps users to encapsulate the set of rules and the facts against which those rules will be matched.

The facts inserted will be inserted into a DataStore, a type-safe entry point. To make everything work, we need to define both the RuleUnit and the DataStore.

package org.acme.kogito.queries;

import org.acme.kogito.model.LoanApplication;
import org.kie.kogito.rules.DataSource;
import org.kie.kogito.rules.DataStore;
import org.kie.kogito.rules.RuleUnitData;

public class LoanUnit implements RuleUnitData {

   private int maxAmount;
   private DataStore<LoanApplication> loanApplications;

   public LoanUnit() {
   	this(DataSource.createStore(), 0);
   }

   public LoanUnit(DataStore<LoanApplication> loanApplications, int maxAmount) {
   	this.loanApplications = loanApplications;
   	this.maxAmount = maxAmount;
   }

   public DataStore<LoanApplication> getLoanApplications() { return loanApplications; }

   public void setLoanApplications(DataStore<LoanApplication> loanApplications) {
   	this.loanApplications = loanApplications;
   }

   public int getMaxAmount() { return maxAmount; }
   public void setMaxAmount(int maxAmount) { this.maxAmount = maxAmount; }
}

And that’s it: REST endpoint to validate Loan Applications will be automatically generated from this Rule Unit.

Running and Using the Application

Running in Dev Mode

To run the microservice in dev mode, use:

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

Running in JVM Mode

When you’re done playing with dev mode you can run it as a standard Java application.

First compile it:

CLI
quarkus build
Maven
./mvnw clean package
Gradle
./gradlew build

Then run it:

java -jar target/quarkus-app/quarkus-run.jar

Running in Native Mode

This same demo can be compiled into native code: no modifications required.

This implies that you no longer need to install a JVM on your production environment, as the runtime technology is included in the produced binary, and optimized to run with minimal resource overhead.

Compilation will take a bit longer, so this step is disabled by default; let’s build a native executable with the following command:

CLI
quarkus build --native
Maven
./mvnw package -Dnative
Gradle
./gradlew build -Dquarkus.package.type=native

After getting a cup of coffee, you’ll be able to run this binary directly:

target/kogito-drl-quickstart-1.0.0-SNAPSHOT-runner

Testing the Application

To test your application, just send a request to the service with giving the person as JSON payload.

curl -X POST http://localhost:8080/find-approved \
    -H 'Content-Type: application/json'\
    -H 'Accept: application/json' \
    -d '{"maxAmount":5000,
          "loanApplications":[
          {"id":"ABC10001","amount":2000,"deposit":1000,
            "applicant":{"age":45,"name":"John"}},
          {"id":"ABC10002","amount":5000,"deposit":100,
            "applicant":{"age":25,"name":"Paul"}},
          {"id":"ABC10015","amount":1000,"deposit":100,
            "applicant":{"age":12,"name":"George"}}
]}'

In the response, the list of the approved applications will be returned:

[{"id":"ABC10001",
    "applicant":{"name":"John","age":45},
    "amount":2000,"deposit":100,"approved":true}]