feat: add rule engine design pattern

pom.xml

@@ -208,6 +208,7 @@
     <module>resource-acquisition-is-initialization</module>
     <module>retry</module>
     <module>role-object</module>
+    <module>rule-engine</module>
     <module>saga</module>
     <module>separated-interface</module>
     <module>serialized-entity</module>

rule-engine/README.md

@@ -0,0 +1,199 @@
+---
+title: "Rule Engine Pattern in Java: Replacing Tangled Conditionals with Composable Rules"
+shortTitle: Rule Engine
+description: "Learn the Rule Engine design pattern in Java. Encapsulate each business rule as an independent object and let an engine evaluate and execute them against a shared context, replacing large nested if/else blocks with small, testable, composable rules."
+category: Behavioral
+language: en
+tag:
+  - Business
+  - Decoupling
+  - Domain
+  - Encapsulation
+  - Extensibility
+---
+
+## Intent of Rule Engine Design Pattern
+
+Encapsulate each business rule as an independent, self-contained object and let an engine evaluate and execute a collection of those rules against a shared context, so that decision logic can grow and change without rewriting a large nested conditional block.
+
+## Detailed Explanation of Rule Engine Pattern with Real-World Examples
+
+Real-world example
+
+> A bank decides whether to approve a loan by checking several independent criteria: the applicant must be old enough, earn enough, and have a good enough credit score. Instead of hard-coding one enormous condition, the bank keeps each criterion as a separate policy on a checklist. A clerk walks the whole checklist for every application, ticks off the criteria that pass, and writes down the ones that fail. Adding a new criterion means adding a line to the checklist, not rewriting the whole approval procedure.
+
+In plain words
+
+> The Rule Engine pattern turns each branch of a giant `if/else` into its own object and hands a collection of them to an engine that runs them all against the same input, collecting which passed and which failed.
+
+## Programmatic Example of Rule Engine Pattern in Java
+
+Each rule separates the **decision** (`evaluate`) from the **action** (`execute`). `evaluate` reports whether a rule's condition holds; `execute` performs the side effect associated with a satisfied rule.
+
+```java
+public interface Rule<T> {
+
+  String name();
+
+  boolean evaluate(T context);
+
+  void execute(T context);
+}
+```
+
+The context is an immutable value object that carries the data the rules inspect.
+
+```java
+public record LoanApplication(
+    int age, double monthlyIncome, double loanAmount, int creditScore) {}
+```
+
+Concrete rules encapsulate one criterion each. New criteria are added by writing new classes — the engine never changes.
+
+```java
+public class MinimumAgeRule implements Rule<LoanApplication> {
+
+  private final int minimumAge;
+
+  public MinimumAgeRule(int minimumAge) {
+    this.minimumAge = minimumAge;
+  }
+
+  @Override
+  public String name() {
+    return "MinimumAgeRule";
+  }
+
+  @Override
+  public boolean evaluate(LoanApplication context) {
+    return context.age() >= minimumAge;
+  }
+
+  @Override
+  public void execute(LoanApplication context) {
+    LOGGER.info("Applicant age {} meets the minimum age of {}.", context.age(), minimumAge);
+  }
+}
+```
+
+The engine holds a defensively copied, immutable list of rules. It evaluates every rule in insertion order, executes the ones that pass, and reports the combined outcome. It never stops at the first failure, so a single run reports *all* the reasons an application was rejected.
+
+```java
+public class RuleEngine<T> {
+
+  private final List<Rule<T>> rules;
+
+  public RuleEngine(List<Rule<T>> rules) {
+    this.rules = List.copyOf(rules);
+  }
+
+  public RuleEngineResult run(T context) {
+    Objects.requireNonNull(context, "context must not be null");
+    List<String> passed = new ArrayList<>();
+    List<String> failed = new ArrayList<>();
+    for (Rule<T> rule : rules) {
+      if (rule.evaluate(context)) {
+        rule.execute(context);
+        passed.add(rule.name());
+      } else {
+        failed.add(rule.name());
+      }
+    }
+    return new RuleEngineResult(failed.isEmpty(), passed, failed);
+  }
+}
+```
+
+The result is an immutable value object describing the run.
+
+```java
+public record RuleEngineResult(
+    boolean approved, List<String> passedRules, List<String> failedRules) {
+
+  public RuleEngineResult {
+    passedRules = List.copyOf(passedRules);
+    failedRules = List.copyOf(failedRules);
+  }
+}
+```
+
+Putting it together, the `App` builds an engine and runs two applications through it.
+
+```java
+var engine =
+    new RuleEngine<>(
+        List.of(
+            new MinimumAgeRule(18),
+            new MinimumIncomeRule(2000.0),
+            new CreditScoreRule(650)));
+
+engine.run(new LoanApplication(30, 3500.0, 15000.0, 720)); // approved
+engine.run(new LoanApplication(17, 1500.0, 15000.0, 720)); // rejected: age and income
+```
+
+Program output:
+
+```
+Applicant age 30 meets the minimum age of 18.
+Applicant income 3500.0 meets the minimum income of 2000.0.
+Applicant credit score 720 meets the minimum score of 650.
+Loan approved. Passed rules: [MinimumAgeRule, MinimumIncomeRule, CreditScoreRule]
+Applicant credit score 720 meets the minimum score of 650.
+Loan rejected. Failed rules: [MinimumAgeRule, MinimumIncomeRule]
+```
+
+### Behavioral decisions
+
+The example commits to the following semantics, each covered by tests:
+
+* `evaluate` returning `true` means the rule **passes** (its condition is satisfied); a passing rule then has its `execute` action run.
+* The engine evaluates **every** rule; it does not stop after the first failure, so all rejection reasons are reported.
+* Outcomes are reported as an immutable `RuleEngineResult` carrying the overall `approved` flag plus the names of the passed and failed rules.
+* Rules execute in **insertion order**.
+* A `null` context passed to `run` throws `NullPointerException`; a `null` rule collection or a `null` rule element is rejected on construction.
+* An engine with **no rules** approves vacuously (nothing failed).
+
+## Class diagram
+
+See [rule-engine.urm.puml](./etc/rule-engine.urm.puml) for the PlantUML class diagram.
+
+## When to Use the Rule Engine Pattern in Java
+
+* Decision logic is a growing set of independent conditions that would otherwise become a large, hard-to-read nested `if/else`.
+* Rules must be added, removed, or reordered without touching the code that coordinates them.
+* You need to report *all* failing conditions, not just the first one.
+* Business rules deserve to be unit tested in isolation.
+
+## Real-World Applications of Rule Engine Pattern in Java
+
+* Loan, insurance, and credit approval workflows.
+* Validation frameworks such as Bean Validation, where each constraint is an independent rule.
+* Fraud detection and risk scoring, where many independent checks contribute to one decision.
+* Pricing, discount, and promotion eligibility engines.
+
+## Benefits and Trade-offs of Rule Engine Pattern
+
+Benefits
+
+* Encapsulation: each rule owns one criterion.
+* Extensibility: new rules are new classes; the engine is closed for modification.
+* Testability: rules and the engine can be tested independently.
+* Transparency: the result lists every passed and failed rule.
+
+Trade-offs
+
+* Debugging a decision means tracing several small objects instead of reading one block.
+* Rule ordering and conflicts must be managed deliberately when rules are not independent.
+* Over-abstracting trivial logic into a rule engine adds indirection that a simple `if` would not.
+
+## Related Java Design Patterns
+
+* [Specification](../specification): combines boolean criteria that an object must satisfy; a Rule Engine orchestrates and executes such criteria.
+* [Chain of Responsibility](../chain-of-responsibility): passes a request along handlers; a Rule Engine instead runs every rule against one context.
+* [Strategy](../strategy): each rule is effectively a pluggable strategy for one decision.
+* [Command](../command): a rule's `execute` action resembles an encapsulated command.
+
+## References and Credits
+
+* [Patterns of Enterprise Application Architecture](https://www.amazon.com/gp/product/0321127420) (Martin Fowler)
+* [Should I use a Rules Engine? (Martin Fowler)](https://martinfowler.com/bliki/RulesEngine.html)

rule-engine/etc/rule-engine.urm.puml

@@ -0,0 +1,61 @@
+@startuml
+package com.iluwatar.ruleengine {
+  interface Rule<T> {
+    + name() : String {abstract}
+    + evaluate(context : T) : boolean {abstract}
+    + execute(context : T) : void {abstract}
+  }
+  class RuleEngine<T> {
+    - rules : List<Rule<T>>
+    + RuleEngine(rules : List<Rule<T>>)
+    + run(context : T) : RuleEngineResult
+    + rules() : List<Rule<T>>
+  }
+  class RuleEngineResult {
+    + RuleEngineResult(approved : boolean, passedRules : List<String>, failedRules : List<String>)
+    + approved() : boolean
+    + passedRules() : List<String>
+    + failedRules() : List<String>
+  }
+  class LoanApplication {
+    + LoanApplication(age : int, monthlyIncome : double, loanAmount : double, creditScore : int)
+    + age() : int
+    + monthlyIncome() : double
+    + loanAmount() : double
+    + creditScore() : int
+  }
+  class MinimumAgeRule {
+    - minimumAge : int
+    + MinimumAgeRule(minimumAge : int)
+    + name() : String
+    + evaluate(context : LoanApplication) : boolean
+    + execute(context : LoanApplication) : void
+  }
+  class MinimumIncomeRule {
+    - minimumIncome : double
+    + MinimumIncomeRule(minimumIncome : double)
+    + name() : String
+    + evaluate(context : LoanApplication) : boolean
+    + execute(context : LoanApplication) : void
+  }
+  class CreditScoreRule {
+    - minimumScore : int
+    + CreditScoreRule(minimumScore : int)
+    + name() : String
+    + evaluate(context : LoanApplication) : boolean
+    + execute(context : LoanApplication) : void
+  }
+  class App {
+    + App()
+    + main(args : String[]) : void
+  }
+}
+RuleEngine --> "*" Rule
+RuleEngine ..> RuleEngineResult
+MinimumAgeRule ..|> Rule
+MinimumIncomeRule ..|> Rule
+CreditScoreRule ..|> Rule
+MinimumAgeRule ..> LoanApplication
+MinimumIncomeRule ..> LoanApplication
+CreditScoreRule ..> LoanApplication
+@enduml

rule-engine/pom.xml

@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+
+    This project is licensed under the MIT license. Module model-view-viewmodel is using ZK framework licensed under LGPL (see lgpl-3.0.txt).
+
+    The MIT License
+    Copyright © 2014-2022 Ilkka Seppälä
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in
+    all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+    THE SOFTWARE.
+
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <parent>
+    <artifactId>java-design-patterns</artifactId>
+    <groupId>com.iluwatar</groupId>
+    <version>1.26.0-SNAPSHOT</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+  <artifactId>rule-engine</artifactId>
+  <dependencies>
+    <dependency>
+      <groupId>org.slf4j</groupId>
+      <artifactId>slf4j-api</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>ch.qos.logback</groupId>
+      <artifactId>logback-classic</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-assembly-plugin</artifactId>
+        <executions>
+          <execution>
+            <configuration>
+              <archive>
+                <manifest>
+                  <mainClass>com.iluwatar.ruleengine.App</mainClass>
+                </manifest>
+              </archive>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+</project>