Module io.github.brantunger.unruly.core
Package io.github.brantunger.unruly.api

Class RuleEvaluation

java.lang.Object
io.github.brantunger.unruly.api.RuleEvaluation
public final class RuleEvaluation extends Object
What a run found out about one rule: whether its condition was true, false, or never evaluated, or whether the run skipped the rule. A run result has one for every loaded rule, in evaluation order, so a caller can answer "why didn't rule X apply?" without a RuleListener.

It's a final class rather than a record, so a later 2.x release can add accessors without breaking code compiled against this one. Two evaluations are equal when their rules and outcomes are, whatever their details: a detail is the language's own object, with whatever equals it has, so it is left out of equals and hashCode.

  • Method Details

    • of

      public static RuleEvaluation of(Rule rule, RuleEvaluation.Outcome outcome)
      Creates an evaluation. The engine creates its own; this is for a class that implements RulesEngine, such as a decorator or a test double, and for tests that compare results.
      Parameters:
      rule - The rule
      outcome - What evaluating its condition found, or that the run skipped it
      Returns:
      The evaluation
      Throws:
      NullPointerException - if an argument is null

    • of

      public static RuleEvaluation of(Rule rule, RuleEvaluation.Outcome outcome, @Nullable Object detail)
      Creates an evaluation with the detail the rule's condition was explained with. The engine creates its own; this is for a class that implements RulesEngine, such as a decorator or a test double, and for tests.
      Parameters:
      rule - The rule
      outcome - What evaluating its condition found, or that the run skipped it
      detail - Why the condition evaluated as it did, in its language's own terms, or null for none
      Returns:
      The evaluation
      Throws:
      NullPointerException - if rule or outcome is null

    • rule

      public Rule rule()
      Returns the rule, the same instance that was passed to RulesEngine.load(java.util.List).
      Returns:
      The rule

    • outcome

      public RuleEvaluation.Outcome outcome()
      Returns what evaluating the rule's condition found, or that the run skipped the rule.
      Returns:
      The outcome

    • detail

      public @Nullable Object detail()
      Returns why the rule's condition evaluated as it did, in its language's own terms, such as the operands a comparison read: the detail the language returned from evaluateWithDetail. The engine always records it when the language gives one. What it is, and what it's worth, is up to the language.
      Returns:
      The detail, or null if there is none. On an evaluation the engine created, that's when the language gave none, or when the rule was skipped or not evaluated. One created with of(Rule, Outcome, Object) has whatever detail it was given, whatever its outcome.

    • equals

      public boolean equals(@Nullable Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Names the rule and its outcome, such as prime-rate=MATCHED. The name is shortened to 200 characters, then escaped, as the engine's error messages show it, so a name with a line break can't start a log line of its own.
      Overrides:
      toString in class Object
      Returns:
      The description