Chapter 19. Migration of a DRL service to a Red Hat build of Kogito microservice

Procedure

1. Create a new module based on the module that contains the rules and Quarkus libraries, providing the REST support:

   Example dependencies for creating a new module

   <dependencies>
   
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy</artifactId>
    </dependency>
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-resteasy-jackson</artifactId>
    </dependency>
   
    <dependency>
      <groupId>org.example</groupId>
      <artifactId>drools-project</artifactId>
      <version>1.0-SNAPSHOT</version>
    </dependency>
   
   <dependencies>

2. Create a REST endpoint.

   The following is an example setup for creating a REST endpoint:

   Example FindApprovedLoansEndpoint endpoint setup

   @Path("/find-approved")
   public class FindApprovedLoansEndpoint {
   
      private static final KieContainer kContainer = KieServices.Factory.get().newKieClasspathContainer();
   
      @POST()
      @Produces(MediaType.APPLICATION_JSON)
      @Consumes(MediaType.APPLICATION_JSON)
      public List<LoanApplication> executeQuery(LoanAppDto loanAppDto) {
      	KieSession session = kContainer.newKieSession();
   
      	List<LoanApplication> approvedApplications = new ArrayList<>();
      	session.setGlobal("approvedApplications", approvedApplications);
      	session.setGlobal("maxAmount", loanAppDto.getMaxAmount());
   
      	loanAppDto.getLoanApplications().forEach(session::insert);
      	session.fireAllRules();
      	session.dispose();
   
      	return approvedApplications;
      }
   }

   In the previous example, a KieContainer containing the rules is created and added into a static field. The rules in the KieContainer are obtained from the other module in the class path. Using this approach, you can reuse the same KieContainer for subsequent invocations related to the FindApprovedLoansEndpoint endpoint without recompiling the rules.

   Note

   The two modules are consolidated in the next process of migrating rule units to a Red Hat build of Kogito microservice using legacy API. For more information, see Migrating DRL rules units to Red Hat build of Kogito microservice using legacy API.

   When the FindApprovedLoansEndpoint endpoint is invoked, a new KieSession is created from the KieContainer. The KieSession is populated with the objects from LoanAppDto resulting from the unmarshalling of a JSON request.

   Example LoanAppDto class

   public class LoanAppDto {
   
      private int maxAmount;
   
      private List<LoanApplication> loanApplications;
   
      public int getMaxAmount() {
      	return maxAmount;
      }
   
      public void setMaxAmount(int maxAmount) {
      	this.maxAmount = maxAmount;
      }
   
      public List<LoanApplication> getLoanApplications() {
      	return loanApplications;
      }
   
      public void setLoanApplications(List<LoanApplication> loanApplications) {
      	this.loanApplications = loanApplications;
      }
   }

   When the fireAllRules() method is called, KieSession is fired and the business logic is evaluated against the input data. After business logic evaluation, the last rule collects all the approved applications in a list and the same list is returned as an output.

3. Start the Red Hat build of Quarkus application.

4. Invoke the FindApprovedLoansEndpoint endpoint with a JSON request that contains the loan applications to be checked.

   The value of the maxAmount is used in the rules as shown in the following example:

   Example curl request

   curl -X POST -H 'Accept: application/json' -H 'Content-Type: 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"}}
   ]}' http://localhost:8080/find-approved

   Example JSON response

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

Procedure

1. Add the following dependencies to the project pom.xml file to enable the use of Red Hat build of Quarkus and legacy API:

   Example dependencies for using Quarkus and legacy API

   <dependencies>
    <dependency>
     <groupId>org.kie.kogito</groupId>
     <artifactId>kogito-quarkus-rules</artifactId>
    </dependency>
    <dependency>
     <groupId>org.kie.kogito</groupId>
     <artifactId>kogito-legacy-api</artifactId>
    </dependency>
   </dependencies>

2. Rewrite the REST endpoint implementation:

   Example REST endpoint implementation

   @Path("/find-approved")
   public class FindApprovedLoansEndpoint {
   
      @Inject
      KieRuntimeBuilder kieRuntimeBuilder;
   
      @POST()
      @Produces(MediaType.APPLICATION_JSON)
      @Consumes(MediaType.APPLICATION_JSON)
      public List<LoanApplication> executeQuery(LoanAppDto loanAppDto) {
      	KieSession session = kieRuntimeBuilder.newKieSession();
   
      	List<LoanApplication> approvedApplications = new ArrayList<>();
      	session.setGlobal("approvedApplications", approvedApplications);
      	session.setGlobal("maxAmount", loanAppDto.getMaxAmount());
   
      	loanAppDto.getLoanApplications().forEach(session::insert);
      	session.fireAllRules();
      	session.dispose();
   
      	return approvedApplications;
      }
   }

   In the rewritten REST endpoint implementation, instead of creating the KieSession from the KieContainer, the KieSession is created automatically using an integrated KieRuntimeBuilder.

   The KieRuntimeBuilder is an interface provided by the kogito-legacy-api module that replaces the KieContainer. Using KieRuntimeBuilder, you can create KieBases and KieSessions in a similar way you create in KieContainer. Red Hat build of Kogito automatically generates an implementation of KieRuntimeBuilder interface at compile time and integrates the KieRuntimeBuilder into a class, which implements the FindApprovedLoansEndpoint REST endpoint.

3. Start your Red Hat build of Quarkus application in development mode.

   You can also use the hot reload to make the changes to the rules files that are applied to the running application. Also, you can create a native image of your rule based application.

Procedure

1. Implement a fact definition using POJO:

   Example implementation of a fact definition using POJO

   package org.kie.kogito.queries;
   
   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; }
   }

   In the previous example, instead of using LoanAppDto the LoanUnit class is bound directly. LoanAppDto is used to marshall or unmarshall JSON requests. Also, the previous example implements the org.kie.kogito.rules.RuleUnitData interface and uses a DataStore to contain the loan applications to be approved.

   The org.kie.kogito.rules.RuleUnitData is a marker interface to notify the decision engine that LoanUnit class is part of a rule unit definition. In addition, the DataStore is responsible to allow the rule engine to react on the changes by firing new rules and triggering other rules.

   Additionally, the consequences of the rules modify the approved property in the previous example. On the contrary, the maxAmount value is considered as a configuration parameter for the rule unit, which is not modified. The maxAmount is processed automatically during the rules evaluation and automatically set from the value passed in the JSON requests.

2. Implement a DRL file:

   Example implementation of a DRL file

   package org.kie.kogito.queries;
   unit LoanUnit; // no need to using globals, all variables and facts are stored in the rule unit
   
   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

   The DRL file that you create must declare the same package as fact definition implementation and a unit with the same name of the Java class. The Java class implements the RuleUnitData interface to state that the interface belongs to the same rule unit.

   Also, the DRL file in the previous example is rewritten using the OOPath expressions. In the DRL file, the data source acts as an entry point and the OOPath expression contains the data source name as root. However, the constraints are added in square brackets as follows:

   $l: /loanApplications[ applicant.age >= 20, deposit >= 1000, amount ⇐ maxAmount ]

   Alternatively, you can use the standard DRL syntax, in which you can specify the data source name as an entry point. However, you need to specify the type of the matched object again as shown in the following example, even if the decision engine can infer the type from the data source:

   $l: LoanApplication( applicant.age >= 20, deposit >= 1000, amount ⇐ maxAmount ) from entry-point loanApplications

   In the previous example, the last rule that collects all the approved loan applications is replaced by a query that retrieves the list. A rule unit defines the facts to be passed in input to evaluate the rules, and the query defines the expected output from the rule evaluation. Using this approach, Red Hat build of Kogito can automatically generate a class that executes the query and returns the output as shown in the following example:

   Example LoanUnitQueryFindApproved class

   public class LoanUnitQueryFindApproved implements org.kie.kogito.rules.RuleUnitQuery<List<org.kie.kogito.queries.LoanApplication>> {
   
      private final RuleUnitInstance<org.kie.kogito.queries.LoanUnit> instance;
   
      public LoanUnitQueryFindApproved(RuleUnitInstance<org.kie.kogito.queries.LoanUnit> instance) {
      	this.instance = instance;
      }
   
      @Override
      public List<org.kie.kogito.queries.LoanApplication> execute() {
      	return instance.executeQuery("FindApproved").stream().map(this::toResult).collect(toList());
      }
   
      private org.kie.kogito.queries.LoanApplication toResult(Map<String, Object> tuple) {
      	return (org.kie.kogito.queries.LoanApplication) tuple.get("$l");
      }
   }

   The following is an example of a REST endpoint that takes a rule unit as input and passing the input to a query executor to return the output:

   Example LoanUnitQueryFindApprovedEndpoint endpoint

   @Path("/find-approved")
   public class LoanUnitQueryFindApprovedEndpoint {
   
      @javax.inject.Inject
      RuleUnit<org.kie.kogito.queries.LoanUnit> ruleUnit;
   
      public LoanUnitQueryFindApprovedEndpoint() {
      }
   
      public LoanUnitQueryFindApprovedEndpoint(RuleUnit<org.kie.kogito.queries.LoanUnit> ruleUnit) {
      	this.ruleUnit = ruleUnit;
      }
   
      @POST()
      @Produces(MediaType.APPLICATION_JSON)
      @Consumes(MediaType.APPLICATION_JSON)
      public List<org.kie.kogito.queries.LoanApplication> executeQuery(org.kie.kogito.queries.LoanUnit unit) {
      	RuleUnitInstance<org.kie.kogito.queries.LoanUnit> instance = ruleUnit.createInstance(unit);
      	return instance.executeQuery(LoanUnitQueryFindApproved.class);
      }
   }

   Note

   You can also add multiple queries and for each query, a different REST endpoint is generated. For example, the FindApproved REST endpoint is generated for find-approved.