faqs

1. Why is Easy Rules called the "The stupid Java rules engine"?

The goal behind Easy Rules is to provide a lightweight rules engine without features that 80% of application do not need. The term "stupid" is actually the perfect term to describe how the engine works: It iterates over a set of ordered rules and execute rules when their conditions are met. This what makes it easy to learn use and use following the KISS principle.

2. I would like to return a value upon a rule execution, how to do that?

By design, rules do not return values. But you can always make your rules return a result after execution. Here is an example:

@Rule(name = "my rule")
public static class MyRule<T> {

    private boolean executed;

    private T result;

    //@Condition
    public boolean when() {
        return true;
    }

    //@Action
    public void then() throws MyException {
        try {
            System.out.println("my rule has been executed");
            result = null; // assign your result here
            executed = true;
        } catch (MyException e) {
            // executed flag will remain false if an exception occurs
            throw e;
        }
    }

    public boolean isExecuted() {
        return executed;
    }

    public T getResult() {
        return result;
    }

}

This rule will return a result if it executes successfully. After firing rules, you query the executed flag on your rule instance and get the execution result.

3. I've registered multiple instances of the same rule with different inputs, but it seems only the first instance is registered. What's happening?

Rules have unique names within a rules engine registry. If you register multiple instances of the same rule, only the first instance will be considered. Other instances will be ignored since they have the same name. Let's see an example:

@Rule(name = "AgeRule",
      description = "Check if person's age is > 18
                     and marks the person as adult")
public class AgeRule {

    private Person person;

    private int adultAge = 18;

    public AgeRule(Person person) {
        this.person = person;
    }

    @Condition
    public boolean isAdult() {
        return person.getAge() > adultAge;
    }

    @Action
    public void markAsAdult(){
        person.setAdult(true);
        System.out.printf(
            "Person %s has been marked as adult",
             person.getName());
    }

}

The Person type is a simple POJO having a name and age fields. Let's register multiple instances of the AgeRule:

Person tom = new Person("Tom", 20);
Person david = new Person("David", 19);

RulesEngine rulesEngine = aNewRulesEngine().build();

//first run
AgeRule ageRule = new AgeRule(tom);
rulesEngine.registerRule(ageRule);
rulesEngine.fireRules();

//second run
ageRule = new AgeRule(david);
rulesEngine.registerRule(ageRule);
rulesEngine.fireRules();

Both Tom and David are adults, so you are expecting to see:

Person Tom has been marked as adult.
Person David has been marked as adult.

But actually you get:

Person Tom has been marked as adult.
Person Tom has been marked as adult.

The second rule instance has been ignored at registration time since it has the same name ( "AgeRule" ) as the first instance.

So how to deal with multiple data using the same rule?

You have 2 solutions: Either you clear rules after the first run using rulesEngine.clearRules(), or register your rule only once, vary input using a setter (that you should add to your rule) and re-fire rules:

//create persons
Person tom = new Person("Tom", 20);
Person david = new Person("David", 19);

//create a rules engine
RulesEngine rulesEngine = aNewRulesEngine().build();
AgeRule ageRule = new AgeRule();
rulesEngine.registerRule(ageRule);

//first run
ageRule.setPerson(tom);
rulesEngine.fireRules();

//second run
ageRule.setPerson(david);
rulesEngine.fireRules();

This is more efficient than registering new instances for each new business data input.

4. Is Easy Rules usable with Android?

Yes. Easy Rules has been made Android compatible since version 1.3

5. Can I use Easy Rules in a web application?

Sure. Easy Rules is very lightweight and can be used both in a standalone application or embedded in an application server, a servlet container or a dependency injection container.

6. How to deal with thread safety?

If you run Easy Rules in a multi-threaded environment, you should take into account the following considerations:

• Easy Rules engine holds a set of rules, it is not thread safe.
• By design, rules in Easy Rules encapsulate the business object model they operate on, so they are not thread safe neither.

Do not try to make everything synchronized or locked down! Easy Rules engine is a very lightweight object and you can create an instance per thread, this is by far the easiest way to avoid thread safety problems.

7. I have another question, how do I do?

Feel free to ask your question in the [Gitter](https://gitter.im/{{ site.github.organization }}/{{ site.github.project }}) channel of the project.