Module io.github.brantunger.unruly.core

Package io.github.brantunger.unruly.api.language

Interface CompiledCondition

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface CompiledCondition

A compiled condition, shared by every run of its rule list.

Several runs can evaluate one compiled condition at the same time, each with its own Session, which only one run uses at a time. Keep what changes while the condition runs in the session.

The engine evaluates a condition with evaluateWithDetail(io.github.brantunger.unruly.api.language.EvaluationContext, io.github.brantunger.unruly.api.language.Session), which a language overrides to explain the result as well as return it.

Implemented by expression languages. A method added to this interface is a default method, so an existing language keeps compiling and working.

Method Summary

Modifier and Type	Method	Description
@Nullable Object	evaluate(EvaluationContext context, Session session)	Evaluates the condition.
default ConditionResult	evaluateWithDetail(EvaluationContext context, Session session)	Evaluates the condition and explains its result.

Method Details

evaluate

@Nullable Object evaluate(EvaluationContext context,
 Session session)
                   throws Exception

Evaluates the condition. The engine doesn't call this method itself: it calls evaluateWithDetail(io.github.brantunger.unruly.api.language.EvaluationContext, io.github.brantunger.unruly.api.language.Session), whose default calls this one, so for a language that doesn't override evaluateWithDetail, an exception this method throws and a result that isn't a Boolean fail the rule as evaluateWithDetail(io.github.brantunger.unruly.api.language.EvaluationContext, io.github.brantunger.unruly.api.language.Session) describes.

Parameters:

context - The facts of the run

session - The run's session for this condition's language, created by the compiler that compiled it

Returns:

The result, which must be a Boolean

Throws:

Exception - if the condition fails

evaluateWithDetail

default ConditionResult evaluateWithDetail(EvaluationContext context,
 Session session)
                                    throws Exception

Evaluates the condition and explains its result. The engine calls this method, never evaluate(io.github.brantunger.unruly.api.language.EvaluationContext, io.github.brantunger.unruly.api.language.Session) directly. When the value is a Boolean, it records the detail, if there is one, on the rule's evaluation in the run's result, unless the run stops first; any other value fails the run, and the detail is dropped. By default, returns ConditionResult.of(Object) of what evaluate(io.github.brantunger.unruly.api.language.EvaluationContext, io.github.brantunger.unruly.api.language.Session) returns, with no detail, so a language that implements only evaluate works as it did.

A language that can explain a condition overrides this method and returns the value and the detail from one evaluation. Its evaluate must return the same value. The detail must not be the session or hold it: the engine keeps the detail after the run, when the session is used by another run or closed.

A decorator that wraps another language's condition must override this method too, and call the wrapped condition's evaluateWithDetail. A wrapper written as a lambda implements only evaluate, so the wrapped condition's detail is dropped.

Parameters:

context - The facts of the run

session - The run's session for this condition's language, created by the compiler that compiled it

Returns:

The result, never null. A value that isn't a Boolean, including null, fails the rule, as does a null result.

Throws:

Exception - if the condition fails. It fails the rule with a RuleExecutionException, except a fatal Error, which run() rethrows unchanged.