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

Class RunOptions

java.lang.Object
io.github.brantunger.unruly.api.RunOptions
public final class RunOptions extends Object
Settings for one run, given to RulesEngine.runWithResult(FactStore, RunOptions). Anything left unset uses what the engine was built with. 
RunResult<Decision> result = engine.runWithResult(facts, RunOptions.withTimeoutOf(Duration.ofMillis(200)));
RunResult<Decision> eu = engine.runWithResult(facts, RunOptions.defaults().withTags(Set.of("eu")));

It's immutable: each with method returns a copy with one setting changed, so a shared instance can't be changed by another caller. It's a final class rather than a record, so a later 2.x release can add settings without breaking code compiled against this one. equals and hashCode compare every setting; one added in a later release takes part too.

  • Method Details

    • defaults

      public static RunOptions defaults()
      Returns the options that change nothing: the run uses what the engine was built with.
      Returns:
      The default options

    • withTimeoutOf

      public static RunOptions withTimeoutOf(Duration timeout)
      Returns options that give the run timeout instead of the engine's run timeout.
      Parameters:
      timeout - How long the run may take; positive
      Returns:
      The options
      Throws:
      NullPointerException - if timeout is null
      IllegalArgumentException - if timeout is zero or negative

    • withTimeout

      public RunOptions withTimeout(Duration timeout)
      Returns a copy of these options that gives the run timeout instead of the engine's run timeout. There is no way to take the engine's timeout away from one run: a run can be given a longer one.

      The deadline is taken from when the run is called, so waiting for a compiled copy of the rules counts towards it, and a run started inside another run's action stops at whichever deadline comes first; see RulesEngineBuilder.runTimeout(Duration).

      Parameters:
      timeout - How long the run may take; positive
      Returns:
      The copy
      Throws:
      NullPointerException - if timeout is null
      IllegalArgumentException - if timeout is zero or negative

    • withTags

      public RunOptions withTags(Collection<String> tags)
      Returns a copy of these options that has the run use only the rules that carry at least one of tags (Rule.getTags()). The run skips every other rule, including rules with no tags: it doesn't evaluate them, and reports them as SKIPPED. Tags are compared exactly, case included. The copy's tags replace any these options had.
      Parameters:
      tags - The tags; not empty, and none null or blank; copied
      Returns:
      The copy
      Throws:
      NullPointerException - if tags is null
      IllegalArgumentException - if tags is empty, or one of them is null or blank

    • timeout

      public @Nullable Duration timeout()
      Returns the timeout these options give the run.
      Returns:
      The timeout, or null if the run uses the engine's

    • tags

      public Set<String> tags()
      Returns the tags that choose the rules the run uses.
      Returns:
      The tags, in String order; unmodifiable, and empty if the run uses every rule

    • equals

      public boolean equals(@Nullable Object other)
      Compares every setting.
      Overrides:
      equals in class Object
      Parameters:
      other - The object to compare with
      Returns:
      Whether other is options with an equal timeout and equal tags

    • hashCode

      public int hashCode()
      Combines the hash codes of every setting, consistently with equals(Object).
      Overrides:
      hashCode in class Object
      Returns:
      The hash code

    • toString

      public String toString()
      Describes the options, such as RunOptions(timeout=PT2S, tags=[eu, retail]). Tags are shortened to 200 characters, then escaped, as the engine's error messages show names.
      Overrides:
      toString in class Object
      Returns:
      The description