ch.maxant.rules

Class Engine

java.lang.Object

ch.maxant.rules.Engine

Direct Known Subclasses:

JavascriptEngine

public class Engine
extends Object

A Rule Engine. Can evaluate rules and execute IActions or simply provide an ordered list of the best matching Rules.

If you are using Java 8, investigate the rules-java8 module!

A fuller explanation of how to use rules can be found in the Javadoc for Rules.

Based on MVEL expression language from Codehaus.

Imagine a tarif system which your business needed to be highly configurable. The business wants to be able to specify new tarifs or update existing ones at any time. The criteria used to determine which tarifs are relevant to a customer wanting to make a purchase are based on the attributes belonging firstly to the person, and secondly to their account. For example, a customer who is under 26 is eligible for a youth tarif. Seniors are eligible for their own tarif too. Additionally, customers who do not get a youth or senior tarif are entitled to a loyalty tarif if they have had an account for more than 24 months.

These business rules can be modelled ina database as a set of string. The data can then be loaded and modelled in the code using the Rule API. Consider the following four rules:

Rule r1 = new Rule("YouthTarif",
"input.age < 26", new StringAction("YT2011"), 3,
"ch.maxant.someapp.tarifs", null);
Rule r2 = new Rule("SeniorTarif",
"input.age > 59", new StringAction("ST2011"), 3,
"ch.maxant.someapp.tarifs", null);
Rule r3 = new Rule("DefaultTarif",
"!#YouthTarif && !#SeniorTarif", new StringAction("DT2011"), 3,
"ch.maxant.someapp.tarifs", null);
Rule r4 = new Rule("LoyaltyTarif",
"#DefaultTarif && input.account.ageInMonths > 24",
new StringAction("LT2011"), 4,
"ch.maxant.someapp.tarifs", null);

The following object model can then be created and used to evaluate the rules.

TarifRequest request = new TarifRequest();
request.setPerson(new Person());
request.setAccount(new Account());
request.getPerson().setAge(35);
request.getAccount().setAgeInMonths(25);

The following code can then be used to determine the best tarif, or list of all matching tarifs:


//will return both DT2011 and LT2011, since both are relevant.
//Since LT2011 has a higher priority, it is first in the list.
List<Rule> matches = engine.getMatchingRules(request);

// returns "LT2011", since the loyalty tarif has a higher priority
String tarif = engine.runBestAction(request, String.class);

See Rule for more details. See EngineTest for more examples. See http://mvel.codehaus.org for full details of the expression language.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_INPUT_NAME the name which scripts should use for the input, unless overriden in the constructor/builder.
protected String	inputName
protected String[]	javascriptFilesToLoad
protected List<Rule>	parsedRules
protected Integer	poolSize
protected boolean	throwExceptionIfCompilationFails
protected Set<String>	uniqueOutcomes

Constructor Summary

Constructors

Modifier	Constructor and Description
	Engine(Collection<Rule> rules, boolean throwExceptionIfCompilationFails)
	Engine(Collection<Rule> rules, String inputName, boolean throwExceptionIfCompilationFails) See Engine(Collection, boolean)
protected	Engine(Collection<Rule> rules, String inputName, boolean throwExceptionIfCompilationFails, Integer poolSize, String[] javascriptFilesToLoad)

Method Summary

Modifier and Type	Method and Description
protected void	compile()
<Input,Output> void	executeAllActions(Input input, Collection<? extends IAction<Input,Output>> actions) See executeAllActions(String, Object, Collection), except that all namespaces will be considered.
<Input,Output> void	executeAllActions(String nameSpacePattern, Input input, Collection<? extends IAction<Input,Output>> actions) Evaluates all rules against the input and then executes all action associated with the positive rules outcomes, in order of highest priority first. Any outcome is only ever executed once! NOTE THAT THIS METHOD DISREGARDS ANY RETURN VALUES OF ACTIONS!!
<Input,Output> Output	executeBestAction(Input input, Collection<? extends IAction<Input,Output>> actions) See executeBestAction(String, Object, Collection), except that all namespaces will be considered.
<Input,Output> Output	executeBestAction(String nameSpacePattern, Input input, Collection<? extends IAction<Input,Output>> actions) Evaluates all rules against the input and returns the result of the action associated with the rule having the highest priority.
<Input> String	getBestOutcome(Input input) See getBestOutcome(String, Object), except that all namespaces will be considered.
<Input> String	getBestOutcome(String nameSpacePattern, Input input) Evaluates all rules against the input and returns the result of the outcome associated with the rule having the highest priority.
<Input> List<Rule>	getMatchingRules(Input input) See getMatchingRules(String, Object), except that all namespaces will be considered.
<Input> List<Rule>	getMatchingRules(String nameSpacePattern, Input input)
protected void	init(Collection<Rule> rules) handles the initialisation

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_INPUT_NAME

public static final String DEFAULT_INPUT_NAME

the name which scripts should use for the input, unless overriden in the constructor/builder.

See Also:

Constant Field Values

uniqueOutcomes

protected final Set<String> uniqueOutcomes

parsedRules

protected List<Rule> parsedRules

throwExceptionIfCompilationFails

protected final boolean throwExceptionIfCompilationFails

inputName

protected final String inputName

javascriptFilesToLoad

protected final String[] javascriptFilesToLoad

poolSize

protected final Integer poolSize

Constructor Detail

Engine

public Engine(Collection<Rule> rules,
              boolean throwExceptionIfCompilationFails)
       throws DuplicateNameException,
              CompileException,
              ParseException

Parameters:

rules - The rules which define the system.

throwExceptionIfCompilationFails - if true, and a rule cannot be compiled, then a CompileException will be thrown.

Throws:

DuplicateNameException - thrown if any rules have the same name within a namespace

CompileException - thrown if throwExceptionIfCompilationFails is true, and a rule fails to compile, because its expression is invalid

ParseException - Thrown if a subrule which is referenced in a rule cannot be resolved.

Engine

public Engine(Collection<Rule> rules,
              String inputName,
              boolean throwExceptionIfCompilationFails)
       throws DuplicateNameException,
              CompileException,
              ParseException

See Engine(Collection, boolean)

Parameters:

inputName - the name of the input in scripts, normally "input", but you can specify your own name here.

Throws:

DuplicateNameException

CompileException

ParseException

Engine

protected Engine(Collection<Rule> rules,
                 String inputName,
                 boolean throwExceptionIfCompilationFails,
                 Integer poolSize,
                 String[] javascriptFilesToLoad)
          throws DuplicateNameException,
                 CompileException,
                 ParseException

Throws:

DuplicateNameException

CompileException

ParseException

Method Detail

init

protected void init(Collection<Rule> rules)
             throws DuplicateNameException,
                    CompileException,
                    ParseException

handles the initialisation

Throws:

DuplicateNameException

CompileException

ParseException

compile

protected void compile()
                throws CompileException

Throws:

CompileException

getBestOutcome

public <Input> String getBestOutcome(Input input)
                              throws NoMatchingRuleFoundException

See getBestOutcome(String, Object), except that all namespaces will be considered.

Type Parameters:

Input - An input object to match against rules.

Throws:

NoMatchingRuleFoundException

getBestOutcome

public <Input> String getBestOutcome(String nameSpacePattern,
                                     Input input)
                              throws NoMatchingRuleFoundException

Evaluates all rules against the input and returns the result of the outcome associated with the rule having the highest priority.

Type Parameters:

Input - An input object to match against rules.

Parameters:

nameSpacePattern - optional. if not null, then only rules with matching namespaces are evaluated.

input - the Object containing all inputs to the expression language rule.

Returns:

The outcome belonging to the best rule which is found.

Throws:

NoMatchingRuleFoundException - If no matching rule was found. Rules must evaluate to true in order to be candidates.

executeBestAction

public <Input,Output> Output executeBestAction(Input input,
                                               Collection<? extends IAction<Input,Output>> actions)
                                        throws NoMatchingRuleFoundException,
                                               NoActionFoundException,
                                               DuplicateNameException

See executeBestAction(String, Object, Collection), except that all namespaces will be considered.

Throws:

NoMatchingRuleFoundException

NoActionFoundException

DuplicateNameException

executeBestAction

public <Input,Output> Output executeBestAction(String nameSpacePattern,
                                               Input input,
                                               Collection<? extends IAction<Input,Output>> actions)
                                        throws NoMatchingRuleFoundException,
                                               NoActionFoundException,
                                               DuplicateNameException

Evaluates all rules against the input and returns the result of the action associated with the rule having the highest priority.

Parameters:

nameSpacePattern - optional. if not null, then only rules with matching namespaces are evaluated.

input - the Object containing all inputs to the expression language rule.

actions - a collection of actions containing one action per possible outcome. The action whose name is equal to the winning outcome will be executed.

Returns:

The result of the IAction with the same name as the winning rules outcome.

Throws:

NoMatchingRuleFoundException - If no matching rule was found. Rules must evaluate to true in order to be candidates.

NoActionFoundException - If no action with a name matching the winning rules outcome was found.

DuplicateNameException - if any actions have the same name.

executeAllActions

public <Input,Output> void executeAllActions(Input input,
                                             Collection<? extends IAction<Input,Output>> actions)
                                      throws NoMatchingRuleFoundException,
                                             NoActionFoundException,
                                             DuplicateNameException

See executeAllActions(String, Object, Collection), except that all namespaces will be considered. NOTE THAT THIS METHOD DISREGARDS ANY RETURN VALUES OF ACTIONS!!

Throws:

NoMatchingRuleFoundException

NoActionFoundException

DuplicateNameException

executeAllActions

public <Input,Output> void executeAllActions(String nameSpacePattern,
                                             Input input,
                                             Collection<? extends IAction<Input,Output>> actions)
                                      throws NoMatchingRuleFoundException,
                                             NoActionFoundException,
                                             DuplicateNameException

Evaluates all rules against the input and then executes all action associated with the positive rules outcomes, in order of highest priority first.

Any outcome is only ever executed once!

NOTE THAT THIS METHOD DISREGARDS ANY RETURN VALUES OF ACTIONS!!

Type Parameters:

Input - The type of input to the actions.

Output - The type of output from the actions.

Parameters:

nameSpacePattern - optional. if not null, then only rules with matching namespaces are evaluated.

input - the Object containing all inputs to the expression language rule.

actions - a collection of actions containing one action per possible outcome. The actions whose names is equal to the positive outcomes will be executed.

Throws:

NoMatchingRuleFoundException - If no matching rule was found. Rules must evaluate to true in order to be candidates.

NoActionFoundException - If no action with a name matching the winning rules outcome was found.

DuplicateNameException - if any actions have the same name.

getMatchingRules

public <Input> List<Rule> getMatchingRules(Input input)

See getMatchingRules(String, Object), except that all namespaces will be considered.

getMatchingRules

public <Input> List<Rule> getMatchingRules(String nameSpacePattern,
                                           Input input)

Type Parameters:

Input - the type of input

Parameters:

nameSpacePattern - optional. if not null, then only rules with matching namespaces are evaluated.

input - the Object containing all inputs to the expression language rule.

Returns:

an ordered list of Rules which evaluated to "true", sorted by Rule.getPriority(), with the highest priority rules first in the list.