easy-rules/README.md

What is Easy Rules?

Easy Rules is a simple yet powerful Java Rules Engine.

It provides useful abstractions to define business rules and apply them easily.

Documentation

Quick introduction

Most business rules can be represented by the following rule definition :

• Name : Unique rule name

• Description : A brief description of the rule

• Priority : Rule priority regarding to other rules

• Conditions : Set of conditions that should be satisfied to apply the rule

• Actions : Set of actions to perform when conditions are satisfied

Easy Rules simply provides an abstraction for each of these key points that define a business rule.

Easy Rules Key APIs

A rule in Easy Rules is an instance of the Rule class :

public class Rule implements Comparable<Rule> {

    private String name;

    private String description;

    private int priority;

    private ConditionTrigger conditionTrigger;

    private ActionPerformer actionPerformer;

    //getters, setters and compareTo methods omitted

}

The name, description and priority attributes are self explanatory.

The ConditionTrigger interface is an abstraction of all conditions that trigger the rule :

public interface ConditionTrigger {

    /**
     * The condition that triggers the rule.
     * @return true if the rule should be applied, false else
     */
    boolean triggerCondition();

}

Implementations of this interface should encapsulate conditions logic that should be satisfied to apply the rule's actions.

The ActionPerformer interface is an abstraction of all actions that should be performed when rule's conditions are satisfied :

public interface ActionPerformer {

    /**
     * Perform an action when a rule is triggered.
     * @throws Exception if an exception occurs during action performing
     */
    void performAction() throws Exception;

}

Easy Rules provides a rule builder to create rules easily like the following snippet :

Rule rule = new RuleBuilder()
        .name("Hello World Rule")
        .description("Say Hello to only duke's friends")
        .conditionTrigger(new HelloWorldConditionTrigger(input.trim()))
        .actionPerformer(new HelloWorldActionPerformer())
        .build();

Easy Rules engine

Easy Rules engine handles a registry of rules with unique names. These rules are applied according to their priorities. By default, lower values represent higher priorities. To override this default behavior, you can extend the Rule class and override compareTo method to provide a custom priority strategy.

Easy Rules provide the following parameters:

Parameter	Type	Required	Default	Description
skipOnFirstAppliedRule	boolean	no	false	skip next applicable rules when a rule is applied
rulePriorityThreshold	int	no	10000	skip next rules if priority exceeds a user defined threshold.

Hello World Sample

This sample shows how to use Easy Rules to say Hello to only duke's friends. The program asks the user if he/she is a friend of duke and says Hello only if he/she responds yes!

public class HelloWorldSampleLauncher {

    public static void main(String[] args) {

        Scanner scanner = new Scanner(System.in);
        System.out.println("Are you a friend of duke? [yes/no]:");
        String input = scanner.nextLine();

        /**
         * Define the rule
         */
        Rule rule = new RuleBuilder()
                .name("Hello World Rule")
                .description("Say Hello to only duke's friends")
                .conditionTrigger(new HelloWorldConditionTrigger(input.trim()))
                .actionPerformer(new HelloWorldActionPerformer())
                .build();

        /**
         * Create a default rules engine and register the business rule
         */
        RulesEngine rulesEngine = new DefaultRulesEngine();
        rulesEngine.registerRule(rule);

        /**
         * Fire rules
         */
        rulesEngine.fireRules();

    }
}

HelloWorldConditionTrigger encapsulates the logic that checks if the user responded 'yes' to the question:

public class HelloWorldConditionTrigger implements ConditionTrigger {

    private String input;

    public HelloWorldConditionTrigger(String input) {
        this.input = input;
    }

    public boolean triggerCondition() {
        //The rule should be applied only if the user's response is yes (duke friend)
        return input.equalsIgnoreCase("yes");
    }

}

HelloWorldActionPerformer encapsulates the logic of the action to perform when the condition is satisfied, in this sample, simply prints 'Hello duke's friend!' to the console:

public class HelloWorldActionPerformer implements ActionPerformer {

    @Override
    public void performAction()  {
        System.out.println("Hello duke's friend!");
    }

}

More samples of how to use Easy Rules can be found here.

Roadmap

• Annotation support : Condition and Action can be defined in any POJO

• Spring support : Easy Rules should be easily configured and used in a Spring container

License

Easy Rules is released under the MIT License.

Contribution

Your feedback is highly appreciated! For any issue, please use the issue tracker.

You can also contribute with pull requests on github.

Many thanks upfront!