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

Class RuleSetInfo

java.lang.Object
io.github.brantunger.unruly.api.RuleSetInfo
public final class RuleSetInfo extends Object
The rules an engine has loaded, from RulesEngine.rules(): the rules themselves, a checksum that identifies them, and when they were loaded. An audit can record the checksum with a decision, and compare it later with the rules a run used (RunResult.ruleSetChecksum()).

Before the first successful RulesEngine.load(List), the engine's rules() has no rules, the checksum of an empty rule list, and a null load time. A run started before a reload finishes with the rules it started with, so its RunResult.ruleSetChecksum() can differ from the checksum() the engine reports afterwards.

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. equals compares every field; a field added in a later release takes part too. hashCode hashes only the checksum and the load time, which equal information shares, so that it doesn't walk every rule.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    checksum()
    Returns a checksum that identifies the loaded rules, so a decision can be tied to a version of them.
    boolean
    equals(@Nullable Object other)
    Compares every field.
    int
    hashCode()
    Combines the hash codes of the checksum and the load time, consistently with equals(Object).
    @Nullable Instant
    loadedAt()
    Returns when the rules finished compiling, by the system clock.
    static RuleSetInfo
    of(List<Rule> rules, String checksum, @Nullable Instant loadedAt)
    Creates the information about a loaded rule list.
    List<Rule>
    rules()
    Returns the rules the last successful RulesEngine.load(List) compiled, in the order they're evaluated: by descending priority, with equal priorities in the order they were given.
    String
    toString()
    Describes the rule set, such as RuleSetInfo(rules=[prime-rate], checksum=9f2c..., loadedAt=2027-06-01T00:00:00Z).

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static RuleSetInfo of(List<Rule> rules, String checksum, @Nullable Instant loadedAt)
      Creates the information about a loaded rule list. The engine creates its own; this is for a class that implements RulesEngine, such as a decorator or a test double.
      Parameters:
      rules - The rules, in evaluation order; copied
      checksum - Their checksum, as checksum() describes it
      loadedAt - When they finished compiling, as loadedAt() describes it, or null if no rules have been loaded
      Returns:
      The information
      Throws:
      NullPointerException - if rules, one of its elements, or checksum is null

    • rules

      public List<Rule> rules()
      Returns the rules the last successful RulesEngine.load(List) compiled, in the order they're evaluated: by descending priority, with equal priorities in the order they were given.
      Returns:
      The rules; unmodifiable, and empty before the first load

    • checksum

      public String checksum()
      Returns a checksum that identifies the loaded rules, so a decision can be tied to a version of them.

      It's the lowercase hex SHA-256 of every rule in evaluation order. Each rule contributes, in this order: its name; its priority as decimal text; the expression language as the engine resolved it (so a rule with no language contributes the engine's default language); its condition; its action; true or false for whether it's enabled; its validFrom and validTo as ISO-8601 text in UTC, as Instant.toString() writes them, such as 2027-06-01T00:00:00Z; and its tags. Each value is written as its length in bytes, as four bytes most significant first, followed by its UTF-8 bytes; a null priority, validFrom or validTo is written as the length -1. A lone surrogate, which UTF-8 can't encode, is written as its three-byte form, as WTF-8 does. U+D800, for example, is ED A0 80, and a high surrogate followed by a low one is one character, in four bytes. The tags are written as how many there are, as four bytes, followed by each tag as a value, in the order of their bytes compared as unsigned numbers. A rule's description isn't included, because it doesn't affect what the rules do, so editing it doesn't change the checksum. Another system can compute the same value from the same rules.

      Returns:
      The checksum; for an empty rule list, the SHA-256 of no bytes

    • loadedAt

      public @Nullable Instant loadedAt()
      Returns when the rules finished compiling, by the system clock.
      Returns:
      When RulesEngine.load(List) finished compiling the rules, before it made any copies at load and swapped the rules in; or null if no rules have been loaded

    • equals

      public boolean equals(@Nullable Object other)
      Compares every field.
      Overrides:
      equals in class Object
      Parameters:
      other - The object to compare with
      Returns:
      Whether other is information with equal rules, in the same order, an equal checksum and an equal load time

    • hashCode

      public int hashCode()
      Combines the hash codes of the checksum and the load time, consistently with equals(Object). It hashes only these, so that it doesn't walk every rule.
      Overrides:
      hashCode in class Object
      Returns:
      The hash code

    • toString

      public String toString()
      Describes the rule set, such as RuleSetInfo(rules=[prime-rate], checksum=9f2c..., loadedAt=2027-06-01T00:00:00Z). Rule names are shortened to 200 characters, then escaped, as the engine's error messages show them.
      Overrides:
      toString in class Object
      Returns:
      The description