From f9b96864d14117d9093961f878b620ea56c6d7ae Mon Sep 17 00:00:00 2001 From: benas Date: Sun, 10 Mar 2013 17:22:40 +0100 Subject: [PATCH] add documentation --- README | 1 - README.md | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 1 deletion(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index e63fb84..0000000 --- a/README +++ /dev/null @@ -1 +0,0 @@ -This file was created by IntelliJ IDEA 12.0.4 for binding GitHub repository \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..f0f6756 --- /dev/null +++ b/README.md @@ -0,0 +1,197 @@ +## 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 : + +```java +public class Rule implements Comparable { + + 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 : + +```java +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 : + +```java +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 : + +```java +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! + +```java +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: + +```java +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: + +```java +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 or by contacting the author directly [by mail][]. + +Many thanks upfront! + +[here]: https://github.com/benas/easy-rules/tree/master/easyrules-samples +[MIT License]: http://opensource.org/licenses/mit-license.php/ +[issue tracker]: https://github.com/benas/easy-rules/issues +[by mail]: mailto:md.benhassine@gmail.com?subject=[Easy Rules] \ No newline at end of file