Visual Guide to Drools Rule Execution¶

10 min

This guide visually explains how the Drools rule engine processes your business rules and facts. By understanding the underlying mechanisms, you'll be better equipped to write efficient rules.

The Big Picture: How Drools Works¶

At a high level, Drools follows this sequence when processing rules:

graph TD
    A[Define Rules] --> B[Insert Facts]
    B --> C[Pattern Matching]
    C --> D[Agenda Creation]
    D --> E[Rule Execution]
    E --> F[Update Working Memory]
    F -->|If changes trigger rules| C

Let's break down each of these steps and understand what happens behind the scenes.

1. Inside the Rule Engine¶

The Drools rule engine has three key components that interact during rule processing:

graph LR
    subgraph "Drools Rule Engine Components"
        PM[Production Memory<br/>Stores Business Rules]
        WM[Working Memory<br/>Stores Facts/Data Objects]
        AG[Agenda<br/>Execution Queue & Order]

        PM -->|Pattern Matching| WM
        WM -->|Rule Activations| AG
        AG -->|Execute Actions| WM
    end

The three key components work together:

Production Memory: Stores your business rules
Working Memory: Stores your facts (data objects)
Agenda: Determines which rules to execute and in what order

Here's a simplified view of how these components interact:

graph TD
    A[Business Rules] --> B[Production Memory]
    B -- Pattern Matching --> C

    subgraph "Rule Engine"
        C[Working Memory<br>Facts/Objects] --> D[Agenda]
    end

    D --> E[Rule Execution]

2. Pattern Matching Process¶

When facts are inserted into working memory, Drools needs to determine which rules should fire. This process is called pattern matching.

The Rete Network Evolution: From Rete to Phreak¶

Drools originally used the Rete algorithm (pronounced "REE-tee" or "RAY-tay") for pattern matching. Since Drools 6, it has been completely replaced by Phreak, an enhanced algorithm that provides:

Lazy evaluation: Rules are only evaluated when needed
Set-oriented propagation: Better performance with large data sets
Improved memory usage: More efficient fact storage
Better scalability: Handles thousands of rules and facts efficiently

While Phreak is architecturally different from Rete, the conceptual model remains similar, making it easier to understand rule execution.

Here's a simplified visualization of how a Rete/Phreak network might look for a rule:

graph TD
    OTN[Object Type Nodes] --> A[Applicant]
    OTN --> B[Loan]
    OTN --> C[Credit]
    OTN --> D[...]
    A --> AN[Alpha Nodes<br>Property Constraints]
    B --> AN
    C --> AN
    AN --> BN[Beta Nodes<br>Joins]
    BN --> TN[Terminal Nodes<br>Rules]

Let's understand each node type:

Object Type Nodes: Filter facts by their class type
Alpha Nodes: Apply single-fact constraints (e.g., age > 18)
Beta Nodes: Join multiple facts together (e.g., $a: Applicant() and $l: Loan(applicant == $a))
Terminal Nodes: Represent rules that are ready to fire

3. From Rule Definition to Execution¶

Let's walk through the lifecycle of a rule from definition to execution using a simple example:

Rule Definition¶

rule "Approve loan for good credit"
when
    $application : LoanApplication(approved == false)
    $applicant : Applicant(creditScore > 700)
then
    modify($application) {
        setApproved(true),
        setReason("Good credit score")
    }
    System.out.println("Loan approved");
end

1. Rule Compilation¶

When you define rules like the one above, Drools compiles them into a network of nodes:

                     ┌─────────────────┐
                     │  Object Type    │
                     │  LoanApplication│
                     └────────┬────────┘
                              │
                              ▼
                     ┌─────────────────┐
                     │  Alpha Node     │
                     │  approved==false│
                     └────────┬────────┘
                              │
                              ▼
           ┌───────────────────────────────┐
           │         Beta Network          │
           │                               │
┌──────────┴─────────┐          ┌──────────┴─────────┐
│   Object Type      │          │    Alpha Node      │
│   Applicant        │─────────▶│    creditScore>700 │
└────────────────────┘          └────────────────────┘
                                         │
                                         ▼
                               ┌─────────────────────┐
                               │   Terminal Node     │
                               │   (Rule Activation) │
                               └─────────────────────┘

2. Fact Insertion¶

When you insert facts, they flow through this network:

Applicant john = new Applicant("John", 30, 720);
LoanApplication johnApp = new LoanApplication(john, 50000);

kSession.insert(john);        // Fact 1
kSession.insert(johnApp);     // Fact 2

Both facts enter working memory and are processed through the network.

3. Pattern Matching and Agenda Creation¶

As facts flow through the network:

The LoanApplication fact is checked against its constraints (not approved)
The Applicant fact is checked against its constraints (credit score > 700)
If both match, the rule is activated and placed on the agenda

graph LR
    subgraph Agenda ["Rule Execution Agenda"]
        A["⭐ 'Approve loan<br/>for good credit'"]
    end

4. Rule Execution¶

When you call fireAllRules(), Drools executes the rules on the agenda:

kSession.fireAllRules();  // Execute activated rules

The rule executes its action (the "then" part), which approves the loan application.

5. Working Memory Update¶

After rule execution, working memory is updated:

Working Memory (Before)          Working Memory (After)
─────────────────────────        ─────────────────────────
Applicant(creditScore=720)       Applicant(creditScore=720)
LoanApplication(approved=false)  LoanApplication(approved=true)

6. Re-evaluation (if needed)¶

Because we used modify() to change the loan application, Drools automatically re-evaluates any rules that might be affected by this change.

4. The Two-Phase Execution Cycle¶

When you call fireAllRules(), Drools enters a two-phase execution cycle:

┌─────────────────────────────┐      ┌─────────────────────────────┐
│                             │      │                             │
│   Agenda Evaluation Phase   │──────▶  Working Memory Actions     │
│                             │      │  Phase                      │
└─────────────┬───────────────┘      └───────────┬─────────────────┘
              │                                  │
              └──────────────────────────────────┘

Agenda Evaluation Phase: The rule engine selects rules that can be executed.
If no more rules can be executed, the cycle ends
If executable rules are found, they're registered in the agenda
Working Memory Actions Phase: The rule engine executes the consequences (actions) of activated rules.
After all consequences are complete, or if fireAllRules() is called again, the process returns to the agenda evaluation phase

5. Conflict Resolution¶

What happens when multiple rules are eligible to fire? Drools uses conflict resolution strategies to determine the execution order:

Salience (Priority)¶

Rules with higher salience values fire before rules with lower values:

rule "High Priority Rule"
    salience 100
when
    // conditions
then
    // actions
end

rule "Low Priority Rule"
    salience 10
when
    // conditions
then
    // actions
end

In this example, the "High Priority Rule" will fire before the "Low Priority Rule" if both are activated.

Agenda Groups¶

Rules can be partitioned into agenda groups, and only rules in the focus group are eligible for execution:

graph TD
    subgraph "Agenda"
        A["Agenda Group: <br> 'calculation' (in focus)"]
        B["⭐ Rule 'Calculate tax'"]
        C["⭐ Rule 'Calculate discount'"]
        D["Agenda Group: <br>'reporting'"]
        E["⭐ Rule 'Generate report'"]
        F["⭐ Rule 'Log transaction'"]

        A --> B
        A --> C
        D --> E
        D --> F
    end

Only rules in the "calculation" group will fire until that group is empty or loses focus.

6. Stateful vs. Stateless Sessions Visualized¶

Stateful Session¶

A stateful session maintains facts across multiple fireAllRules() calls:

 ┌─────────────────────┐
 │   Stateful Session  │
 └──────────┬──────────┘
            │
            ▼
┌───────────────────────┐
│     Working Memory    │
│  ───────────────────  │      ┌─────────────┐
│  Applicant(John)      │◄─────┤ insert(john)│
│                       │      └─────────────┘
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│     Working Memory    │
│  ───────────────────  │      ┌──────────────────┐
│  Applicant(John)      │◄─────┤ insert(johnApp)  │
│  LoanApplication(...) │      └──────────────────┘
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│     Working Memory    │
│  ───────────────────  │      ┌──────────────────┐
│  Applicant(John)      │◄─────┤ fireAllRules()   │
│  LoanApplication(...) │      └──────────────────┘
│ [AFTER RULE EXECUTION]│
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│     Working Memory    │
│  ───────────────────  │      ┌──────────────────┐
│  Applicant(John)      │◄─────┤ insert(mary)     │
│  LoanApplication(...) │      └──────────────────┘
│  Applicant(Mary)      │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│     Working Memory    │
│  ───────────────────  │      ┌──────────────────┐
│  Applicant(John)      │◄─────┤ dispose()        │
│  LoanApplication(...) │      └──────────────────┘
│  Applicant(Mary)      │
│  [SESSION DESTROYED]  │
└───────────────────────┘

Stateless Session¶

A stateless session processes all facts in a single operation and doesn't maintain state:

┌───────────────────────┐
│   Stateless Session   │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  Insert all facts     │    ┌─────────────────────────┐
│  Execute all rules    │◄───┤ execute([john, johnApp])│
│  Dispose automatically│    └─────────────────────────┘
└───────────────────────┘

┌───────────────────────┐
│   Stateless Session   │
└──────────┬────────────┘
           │
           ▼
┌───────────────────────┐
│  Insert all facts     │    ┌─────────────────────────┐
│  Execute all rules    │◄───┤ execute([mary, maryApp])│
│  Dispose automatically│    └─────────────────────────┘
└───────────────────────┘

Each execute() call is a separate, isolated operation with no shared state between calls.

7. Truth Maintenance and Logical Insertions¶

Drools supports automatic truth maintenance through logical insertions. When you use insertLogical() instead of insert(), the fact is automatically retracted when the conditions that led to its insertion are no longer true.

                   Initial State
┌─────────────────────────────────────────┐
│ Working Memory                          │
│ ───────────────                         │
│ Person(age=16)                          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Rule "Infer Child" fires                │
│ when                                    │
│   $p : Person(age < 18)                 │
│ then                                    │
│   insertLogical(new IsChild($p))        │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Working Memory                          │
│ ───────────────                         │
│ Person(age=16)                          │
│ IsChild(person=Person(age=16))          │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Update Person age                       │
│ person.setAge(20)                       │
│ update(factHandle, person)              │
└─────────────────┬───────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────┐
│ Working Memory                          │
│ ───────────────                         │
│ Person(age=20)                          │
│ [IsChild fact automatically retracted]  │
└─────────────────────────────────────────┘

8. Event Processing in Drools¶

For time-based events, Drools supports two processing modes:

Cloud Mode (Default)¶

All events are treated as regular facts with no temporal constraints:

┌───────────────────────────────────────────┐
│ Working Memory (Cloud Mode)               │
│ ───────────────────────────               │
│ StockTick(symbol="AAPL", price=150.00)    │
│ StockTick(symbol="MSFT", price=245.00)    │
│ StockTick(symbol="AAPL", price=152.00)    │
│                                           │
│ [Events processed in insertion order      │
│  regardless of their time stamps]         │
└───────────────────────────────────────────┘

Stream Mode¶

Events are processed with temporal awareness:

┌───────────────────────────────────────────┐
│ Working Memory (Stream Mode)              │
│ ───────────────────────────               │
│ Time: 10:01:00                            │
│ StockTick(symbol="AAPL", price=150.00)    │
│                                           │
│ Time: 10:02:00                            │
│ StockTick(symbol="MSFT", price=245.00)    │
│                                           │
│ Time: 10:03:00                            │
│ StockTick(symbol="AAPL", price=152.00)    │
│                                           │
│ [Events processed in chronological order] │
└───────────────────────────────────────────┘

9. Sliding Windows¶

In stream mode, you can define sliding windows of time or length to process only recent events:

Time Window¶

┌───────────────────────────────────────────┐
│ Sliding Time Window (2 minutes)           │
│ ─────────────────────────────             │
│                                           │
│ Current time: 10:03:00                    │
│                                           │
│ In window:                                │
│ ──────────                                │
│ StockTick(time=10:02:00, symbol="MSFT")   │
│ StockTick(time=10:03:00, symbol="AAPL")   │
│                                           │
│ Outside window (expired):                 │
│ ─────────────────────                     │
│ StockTick(time=10:01:00, symbol="AAPL")   │
└───────────────────────────────────────────┘

Length Window¶

┌───────────────────────────────────────────┐
│ Sliding Length Window (last 2 events)     │
│ ────────────────────────────────          │
│                                           │
│ In window:                                │
│ ──────────                                │
│ StockTick(time=10:02:00, symbol="MSFT")   │
│ StockTick(time=10:03:00, symbol="AAPL")   │
│                                           │
│ Outside window:                           │
│ ───────────────                           │
│ StockTick(time=10:01:00, symbol="AAPL")   │
└───────────────────────────────────────────┘

10. Temporal Operators¶

Drools supports temporal operators to define relationships between events:

┌─────────────────────────────────────────────────────────────────────┐
│ Temporal Relationship: "after"                                      │
│ ────────────────────────────                                        │
│                                                                     │
│ StockTick(symbol="AAPL", price=150)  │                              │
│                           │          │                              │
│                           │          │                              │
│                           │          ▼                              │
│                           │     StockTick(symbol="AAPL", price=152) │
│                           │                                         │
│                           │                                         │
│             Event B occurs after Event A                            │
└─────────────────────────────────────────────────────────────────────┘

Drools supports many temporal operators including: - after/before - coincides - during/includes - finishes/finished by - meets/met by - overlaps/overlapped by - starts/started by

11. Property Reactivity¶

By default, Drools only re-evaluates rules when properties that are actually used in constraints change:

┌───────────────────────────────────────────────────┐
│ Rule:                                             │
│ "Approve high value customer"                     │
│ when                                              │
│   Customer(status == "Gold", spending > 1000)     │
│ then                                              │
│   // Actions                                      │
└────────────────────┬──────────────────────────────┘
                     │
                     ▼
┌───────────────────────────────────────────────────┐
│ Working Memory                                    │
│ ─────────────                                     │
│ Customer(                                         │
│   name="John",                                    │
│   age=35,           ← Changing this property      │
│   status="Gold",    ← Reactive property           │
│   spending=1200     ← Reactive property           │
│ )                                                 │
└───────────────────────────────────────────────────┘

When you change the age property, the rule isn't re-evaluated because the rule doesn't use it. When you change status or spending, the rule is re-evaluated.

This gives you visibility into when: - Facts are inserted, updated, or deleted - Rules are activated or fired - Agenda groups are pushed or popped

Logging¶

Configure SLF4J logging to see detailed information:

<logger name="org.drools" level="debug"/>

This creates a log file that can be opened with the Audit View tool.

13. Life Cycle of a Drools Application¶

Here's the typical lifecycle of a Drools application:

graph TD
    A[Define Facts Models] --> B[Author Rules]
    B --> C[Insert Facts]
    C --> D[Gather Rules Required]
    D --> E[Determine Order to Fire]
    E --> F[Fire Rules]
    F --> G[Get Results]
    G -->|Are there more rules <br> to process?| E
    G -->|Done| H[Complete]

Summary¶

You've now seen how the Drools rule engine processes rules and facts. Understanding these internal mechanisms will help you:

Write more efficient rules: By understanding how the pattern matching works, you can structure your rules for better performance
Troubleshoot issues: When rules don't fire as expected, you know where to look
Choose the right session type: Based on your use case, you can select stateful or stateless sessions
Work with events: You can process time-based events using stream mode and sliding windows

The visual representations in this guide are simplified, but they provide a mental model of how Drools works under the hood. As you become more familiar with Drools, you'll develop an intuition for how changes to your rules and facts affect rule execution.

Remember that Drools is designed to separate business logic from application code. This separation makes your systems more maintainable and adaptable to changing requirements.

Was this page helpful?