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

Interface RunContext

public sealed interface RunContext
One run of an engine, given to RuleListener's run callbacks. It identifies the run, so a listener can correlate what it sees without a ThreadLocal of its own: a tracing span, a timer or a counter belongs to the runId(), and parent() tells a run started from inside an action apart from the run around it.

Implemented by the engine, which passes it to a listener. It's sealed, so a listener can't implement it; test a listener by running an engine, as Callbacks in the listener guide says. Because only the engine implements it, a later release can add methods to it without breaking listeners.

Identity: a context equals only itself, so it can key a map from beforeRun to afterRun or onRunError, however the facts change during the run and whatever another engine's runs look like. Its toString() names the run, its parent, the match policy, the checksum, the tags and when the run started, never the facts; the tags are shortened to 200 characters, then escaped, as the engine's error messages show names.

See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    Map<String,@Nullable Object>
    facts()
    Returns the fact values the run was given, the same read-only view the rule callbacks receive.
    String
    matchPolicy()
    Returns which rules the engine fires: "firstMatch" for the action of the highest-priority matching rule, "allMatches" for every match in priority order, or "uniqueMatch" for the one match, failing the run when there are more.
    @Nullable RunContext
    parent()
    Returns the run this one started from, for a run an action or a listener started on the same engine and thread.
    String
    ruleSetChecksum()
    Returns the checksum of the rules this run uses, as RuleSetInfo.checksum() describes it.
    long
    runId()
    Returns the run's identifier, which counts up from one within an engine.
    Instant
    startedAt()
    Returns when the run started, by the engine's clock: the one instant the run read from it, which judged every rule's validFrom and validTo.
    Set<String>
    tags()
    Returns the tags the run was given with RunOptions.withTags(java.util.Collection): the run uses only the rules that carry at least one of them, and reports the others as SKIPPED.

  • Method Details

    • runId

      long runId()
      Returns the run's identifier, which counts up from one within an engine. Two engines use the same numbers, so use the context itself, or the pair of engine and id, to tell runs apart across engines.
      Returns:
      The identifier, the first run of an engine being 1

    • parent

      @Nullable RunContext parent()
      Returns the run this one started from, for a run an action or a listener started on the same engine and thread.
      Returns:
      The enclosing run, or null if this run wasn't started from another run of the same engine

    • matchPolicy

      String matchPolicy()
      Returns which rules the engine fires: "firstMatch" for the action of the highest-priority matching rule, "allMatches" for every match in priority order, or "uniqueMatch" for the one match, failing the run when there are more. It's a String rather than an enum, so a later release can add a policy without breaking code that switches over the values it knows.
      Returns:
      The policy's name

    • ruleSetChecksum

      String ruleSetChecksum()
      Returns the checksum of the rules this run uses, as RuleSetInfo.checksum() describes it.
      Returns:
      The checksum

    • facts

      Map<String,@Nullable Object> facts()
      Returns the fact values the run was given, the same read-only view the rule callbacks receive. The engine checks the fact names after RuleListener.beforeRun(RunContext), so a name no language can refer to is still in this map when beforeRun runs, and fails the run afterwards. A value the engine widened to a fact's declared primitive type, as RulesEngineBuilder.fact(String, Class) describes, is here as it was widened, such as a Long for an Integer the run supplied, already when beforeRun runs.
      Returns:
      The fact values by name. Writing to it throws UnsupportedOperationException.

    • tags

      Set<String> tags()
      Returns the tags the run was given with RunOptions.withTags(java.util.Collection): the run uses only the rules that carry at least one of them, and reports the others as SKIPPED. With startedAt() and the ruleSetChecksum(), it tells which rules the run uses, so an audit record can say why one was skipped. The run's conditions and actions get the same set as EvaluationContext.tags().
      Returns:
      The run's RunOptions.tags(): in String order, unmodifiable, and empty if the run uses every rule

    • startedAt

      Instant startedAt()
      Returns when the run started, by the engine's clock: the one instant the run read from it, which judged every rule's validFrom and validTo. A fixed clock gives every run the same instant. It isn't comparable to RuleSetInfo.loadedAt() or the run's deadline, which are measured with the system clock. The run's conditions and actions get the same instant as EvaluationContext.startedAt().
      Returns:
      The instant the run started at