From 9a3609fd12a51b6a9fc2ac7b2190ae4c6bb54fa3 Mon Sep 17 00:00:00 2001
From: Mahmoud Ben Hassine <md.benhassine@gmail.com>
Date: Mon, 29 Jun 2015 00:41:01 +0200
Subject: [PATCH] add faq section

---
 site/_includes/docs_contents.html    |   3 +
 site/get-involved/faq.md             | 164 +++++++++++++++++++++++++++
 site/get-involved/release-notes.html |  19 ++++
 3 files changed, 186 insertions(+)
 create mode 100644 site/get-involved/faq.md

diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html
index 2c969fc..1cdb7af 100644
--- a/site/_includes/docs_contents.html
+++ b/site/_includes/docs_contents.html
@@ -59,6 +59,9 @@
         <li class="{% if page.title == "Release notes" %}current{% endif %}">
             <a href="{{ site.url }}/get-involved/release-notes.html">Release notes</a>
         </li>
+        <li class="{% if page.title == "FAQ" %}current{% endif %}">
+        <a href="{{ site.url }}/get-involved/faq.html">FAQs</a>
+        </li>
         <li>
             <a target="_blank" href="https://github.com/benas/easy-rules">Source repository</a>
         </li>
diff --git a/site/get-involved/faq.md b/site/get-involved/faq.md
new file mode 100644
index 0000000..74b261b
--- /dev/null
+++ b/site/get-involved/faq.md
@@ -0,0 +1,164 @@
+---
+layout: docs
+title: FAQ
+prev_section: get-involved/release-notes
+doc: true
+---
+
+## <a name="1"></a>[1. Why is Easy Rules called the "The stupid Java rules engine"?](#1)
+
+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.
+
+## <a name="2"></a>[2. I would like to return a value upon a rule execution, how to do that?](#2)
+
+By design, rules do not return values. But you can always make your rules return a result after execution. Here is an example:
+
+```java
+@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.
+
+## <a name="3"></a>[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?](#3)
+
+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:
+
+```java
+@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.\n",
+             person.getName());
+    }
+
+}
+```
+
+The `Person` type is a simple Pojo having a `name` and `age` fields. Let's register multiple instances of the `AgeRule`:
+
+```java
+Person tom = new Person("Tom", 20);
+Person david = new Person("David", 18);
+
+RulesEngine rulesEngine = aNewRulesEngine().build();
+
+//first run
+AgeRule ageRule = new AgeRule(tom);
+rulesEngine.registerRule(ageRule);
+rulesEngine.fireRules();
+
+//first 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 you see only:
+
+```
+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:
+
+```java
+//create persons
+Person tom = new Person("Tom", 20);
+Person david = new Person("David", 18);
+
+//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.
+
+## <a name="4"></a>[4. Is Easy Rules usable with Android?](#4)
+
+Yes. Thanks to the community, Easy Rules has been made Android compatible since version 1.3
+
+## <a name="5"></a>[5. Can I use Easy Rules in a web application?](#5)
+
+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.
+
+## <a name="6"></a>[6. I have another question, how do I do?](#6)
+
+Feel free to ask your question in the [Gitter](https://gitter.im/benas/easy-rules) channel of the project: [![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/benas/easy-rules?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
\ No newline at end of file
diff --git a/site/get-involved/release-notes.html b/site/get-involved/release-notes.html
index 2236a07..814fcdc 100644
--- a/site/get-involved/release-notes.html
+++ b/site/get-involved/release-notes.html
@@ -2,6 +2,7 @@
 layout: news
 title: "Release notes"
 prev_section: tutorials/spring-tutorial
+next_section: get-involved/faq
 doc: true
 ---
 
@@ -10,6 +11,24 @@ doc: true
         <a href="/get-involoved/release-notes.html">{{ page.title }}</a>
     </h2>
 
+    <div class="release">
+        <span class="post-category">
+            <span class="label">Version 2.1.0</span>
+        </span>
+        <div class="post-meta">
+            <span class="post-date">2015-06-28</span>
+        </div>
+        <div class="post-content">
+            <p>This release brings the following new features:</p>
+            <ul>
+                <li>New APIs to embed easy rules in a <a href="http://www.spring.io" target="_blank">Spring</a> container.</li>
+                <li>New APIs to schedule a rules engine using <a href="http://www.quartz-scheduler.org" target="_blank">Quartz</a> (<a href="https://github.com/benas/easy-rules/pull/15" target="_blank">PR #15</a>).</li>
+                <li>New maven archetype to create a quick start project.
+            </ul>
+            <p>This version also added new tutorials and many improvements and bug fixes.</p>
+        </div>
+    </div>
+
     <div class="release">
         <span class="post-category">
             <span class="label">Version 2.0.0</span>