Rules

Rules are the basic building blocks of RuleBook. They are the individual conditions an actions that evaluate and act on facts, respectively. Rules contain facts and optionally a Result. And all Rules implement the com.deliveredtechnologies.rulebook.model.Rule interface.

RuleBook comes packaged with a single implementation of the Rule interface, GoldenRule. However, you are welcome to create your own implementation of the Rule interface and use that instead. But you shouldn't need to. GoldenRule should have all you need. The rest of the page will discuss Rules in the context of the functionality implemented in GoldenRule.

Standalone Rules

A Rule, by itself can accept facts, evaluate a condition based on those facts, execute one or more actions if that condition evaluates to true and (optionally) maintain a Result. The real magic comes when Rules are chained together in a RuleBook. However, this page limits the discussion to how a Rule itself works. If you want to know more about how Rules are executed in the context of a RuleBook, see the RuleBook page in this Wiki.

A Rule can have a single condition, which is a Predicate functional interface. When that condition evaluates to true, each of the actions specified for the Rule are executed in the order in which they were specified. If no condition exists for a Rule, the condition is assumed to be true.

Rules are invoked using the invoke() method, which returns a boolean result. The invoke() method returns true if the actions of the Rule execute without error. Otherwise, the invoke() method will return false.

Evaluating a Rule's Condition

Since a Rule's condition is supplied by a Predicate functional interface, a common way to define the implementation of that interface is through Java's Lambda syntax. The type of the parameter used in the Predicate is NameValueReferableTypeConvertibleMap, which is really just NameValueReferableMap (impl: FactMap) with some type conversion convenience methods attached to it. Of course, as a Predicate, the return type is boolean.

An important thing to note about evaluating conditions is that facts supplied to the condition are filtered by the type of facts evaluated by the Rule. Below is an example that illustrates this point.

Rule<String, Object> rule = new GoldenRule<>(String.class);
rule.addFacts(new Fact<String>("str", "String Value"), new Fact<Boolean>("bool", true));
rule.setCondition(facts -> facts.getValue("bool")); 
rule.addAction(facts -> System.out.println(facts.getValue("str")));
rule.invoke(); //returns false; invocation of the condition will fail since "bool" fact is not available

In the above example, the action that prints the value of the "str" fact is not executed. The reason the action is not executed is because the type of the facts used in the Rule is String, but "bool" is type Boolean. And since Boolean does not match the type of facts used by the Rule, it is not available in the Rule's condition.

Executing a Rule's Action(s)