Module io.github.brantunger.unruly.core

Package io.github.brantunger.unruly.api

@NullMarked package io.github.brantunger.unruly.api

The engine's public API: build an engine, give it rules, run it against facts, and observe its runs.

Where to start:

1. RulesEngineBuilder — choose a match policy with firstMatch, allMatches or uniqueMatch, give it an output supplier, and build() the engine.
2. Rule — a name, a condition, an action, a priority and the language they're written in, from Rule.builder().
3. RulesEngine.load(java.util.List) — compiles a rule list; call it again at any time to swap in new rules.
4. RulesEngine.run(io.github.brantunger.unruly.api.FactStore) — returns the output object, or null when no rule matched; RulesEngine.runWithResult(io.github.brantunger.unruly.api.FactStore) also reports which rules fired and what each condition evaluated to.
5. RuleListener — callbacks around every run, condition and action.

Types:

• Engine: RulesEngine, RulesEngineBuilder, RunOptions (settings for one run) and RuleSetInfo (the rules an engine has loaded)
• Rules: Rule
• Facts: FactStore and its built-in implementation FactMap; FactReference and its built-in implementation Fact
• Results and output: RunResult, RuleEvaluation (one rule's outcome), OutputWriter (how properties an action returns are set on the output) and OutputConverter (how a rule's language converts such a property's value for a setter's type)
• Observing runs: RuleListener, RunContext (one run, as its listeners see it) and LoggingRuleListener

Threads: an engine is thread-safe once built: run() from any number of threads, and load() at any time. The builder and a FactMap aren't. Listeners, the output supplier and an output writer are called from every thread that runs the engine, so they must be.

Types in this package are non-null unless annotated Nullable.

See Also:

• Quick start
• The guides

Related Packages

Package	Description
io.github.brantunger.unruly.api.exception	The exceptions the engine throws, all unchecked and all extending UnrulyException.
io.github.brantunger.unruly.api.language	The interfaces an expression language implements, so rule conditions and actions can be compiled and run, and the ones the engine passes to it.

Class	Description
Fact<T extends @Nullable Object>	The built-in, immutable FactReference.
FactMap<T extends @Nullable Object>	The built-in FactStore: a map from each fact's name to its FactReference, backed by a HashMap.
FactReference<T extends @Nullable Object>	A named value that rules run against.
FactStore<T extends @Nullable Object>	A store of facts, each kept under its name.
LoggingRuleListener	A RuleListener that logs each rule's callbacks through SLF4J at DEBUG: beforeEvaluate, afterEvaluate, beforeExecute, afterExecute and onError.
OutputConverter	Converts a value an action returned with ActionResult.set(java.util.Map) to the type of a setter, as the rule's expression language understands its own values.
OutputWriter<O>	Sets a property on the output object.
Rule	A rule: a condition that decides whether it fires, and an action that runs when it does, with a name, a priority and the language they're written in.
Rule.RuleBuilder	Builds a Rule.
RuleEvaluation	What a run found out about one rule: whether its condition was true, false, or never evaluated, or whether the run skipped the rule.
RuleEvaluation.Outcome	What evaluating a rule's condition found, or that the run skipped the rule.
RuleListener	A listener interface to hook into the lifecycle of rule evaluation and execution.
RulesEngine<O>	Runs rules against facts: it evaluates each Rule's condition and fires the actions of the rules that match, as its match policy decides.
RulesEngineBuilder<O>	Configures and builds a RulesEngine.
RuleSetInfo	The rules an engine has loaded, from RulesEngine.rules(): the rules themselves, a checksum that identifies them, and when they were loaded.
RunContext	One run of an engine, given to RuleListener's run callbacks.
RunOptions	Settings for one run, given to RulesEngine.runWithResult(FactStore, RunOptions).
RunResult<O>	What one run did: the output object, the rules that fired, what each rule's condition evaluated to, the checksum of the rules it used, and the tags and start time that chose which of them it used.