What is the Executable Model?
The Executable Model is a new way to execute business rules in Drools.
It’s based on a Java representation of the rule structure that provides a few advantages such as faster startup time and better memory allocation at runtime.
You can check out the details in the Drools Documentation or in other blog posts such as Mario’s.
KJARs built with the kie-maven-plugin
have the Executable Model enabled since 7.33.0.Final by default and it’s the main technology underneath Kogito.
With the "Executable Model Compiler", a module you can find in the drools-model-compiler
directory, DRL files are transformed into a Java DSL.
How to start contributing
Drools is a really big open source project, and finding the best way to contribute to it might not be easy.
Luckily, the Executable Model Compiler is a good way to start, for various reasons:
- It’s a fairly new project (as today it’s been more or less three years since the inception)
- It doesn’t require deep understanding of the Drools’ internal algorithm, PHREAK
- There always is a former counterpart to verify the code against
Regarding the third point, we want Drools to behave in the exact same way while using the former runtime (also called DRL
) and the new one (called PatternDSL
).
Contributing: showing a problem
Imagine that you’re interested in contributing to Drools, what should you do when you find a problem and you think it’s related to the Executable Model?
Firstly we should understand where the problem is in Drools and if it’s eventually related to the Executable Model.
To do that, we need to create the smallest piece of code that shows the problem: this is what we called a "bug reproducer" (also just "reproducer").
If you provide a bug report to Zulip, mailing lists or Stack Overflow
the team will ask you to create such reproducer. There are two ways to do it:
1) If you’re familiar with the Drools GitHub repository you can write the test directly in your own fork of the original repository and create a PR against it.
This is probably the best way to proceed, as it allows all the Drools’ developers to check the problem faster
2) Create another separate project that shows the problem
Method #1: create a reproducer in drools.git
Start by building the Drools project reading the Drools Source Code page.
You can either decide to build it using droolsjbpm-build-bootstrap or building only the Drools module with mvn clean install
. The second one is definitely faster.
Once you have the project up and running you can open it with your preferred IDE and take a look at the tests in the drools-model-compiler
module, for example org.drools.modelcompiler.CompilerTest
.
If you run these tests you’ll see they’re executed twice, once against the DRL
mode and the other against the PatternDSL
. It’s important that the tests run in both ways. If you see a difference in the execution, please create a PR. And if you want to fix it on your own, try – we love to see new contributors.
Method #2: create a self contained project
Let’s use the Drools archetype and verify that your small reproducer is working against Drools Legacy.
Start by creating a KJAR using the Maven Archetype, modify the rules and the test to verify everything is working accordingly. The default archetype will run the test against the DRL mode.
Change the generated model to build an executable model KJAR. To do so, switch in the pom.xml
from drools-engine-classic
to drools-engine
. Also add the drools-model-compiler
dependency.
Compile the project using maven and the command line. Use
mvn clean install -DskipTests=true
as it’ll try run the tests using the classic engine but we don’t have the drools-mvel
dependency in the class path anymore.
Verify the Executable Model has been built in the KJAR, you can for example using this command to view the content inside the KJAR:
jar -tf target/name_of_the_kjar.jar
You will see all the Executable Model classes under and the drools-model
file.
Another way to do it is to check the maven log for this phrase:
[INFO] Found 7 generated files in Canonical Model
[INFO] Generating /Users/lmolteni/git/contribute/reproducer-kjar/target/generated-sources/drools-model-compiler/main/java/./org/example/P41/LambdaExtractor41A2683D222972683028514525A5437B.java
...
Create another project called runner
that has the original project as a dependency in the Maven pom.xml
.
The same archetype can be used again, but you have to change a few things
- Remove all the classes in
src/main/java
- Remove the DRL files, as this project only consumes KJARs
- Remove the
kmodule.xml
file - Remove the
kie-maven-plugin
from the build. Again, we don’t want to build KJARs here, only to use them. - Switch in the
pom.xml
fromdrools-engine-classic
todrools-engine
. - Remove the
kjar
packaging in pom.xml - Add the original KJAR dependency
<dependency>
<groupId>org.example</groupId>
<artifactId>reproducer-kjar</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
- Move the test from the original reproducer to this module
- Never call
kContainer.verify();
while using Executable Model KJARs as this will retrigger the build
Run the test. This time the test will run using the Executable Model.
You can see it because there will be this line in the logs
2021-06-15 11:32:29,576 INFO [org.drools.modelcompiler.CanonicalKieModuleProvider] (main) Artifact org.example:reproducer-kjar:1.0-SNAPSHOT has executable model
This can probably be abstracted in a new archetype, let us know if you’re interested and we can work of it.
Summary
In this article, we saw how to provide a small reproducer to verify an unexpected behaviour in Drools Executable Model and to provide the developers some way to verify the unexpected behaviour.
Please try and contribute to Drools Executable Model!