From 3871e3df673203abbc062cdf6cbfe04fddf55ece Mon Sep 17 00:00:00 2001 From: Mahmoud Ben Hassine Date: Thu, 25 Jun 2015 09:00:33 +0200 Subject: [PATCH] add documentation and tutorial about Spring support --- easyrules-samples/pom.xml | 33 +++++++ .../easyrules/samples/spring/DummyRule.java | 19 ++++ .../easyrules/samples/spring/Launcher.java | 45 +++++++++ .../samples/spring/application-context.xml | 19 ++++ pom.xml | 6 ++ site/_includes/docs_contents.html | 6 ++ site/get-involved/release-notes.html | 2 +- site/tutorials/scheduling-engine.md | 2 +- site/tutorials/spring-tutorial.md | 99 +++++++++++++++++++ site/user-guide/embedding-rules-engine.md | 85 ++++++++++++++++ site/user-guide/scheduling-rules-engine.md | 14 ++- 11 files changed, 320 insertions(+), 10 deletions(-) create mode 100644 easyrules-samples/src/main/java/org/easyrules/samples/spring/DummyRule.java create mode 100644 easyrules-samples/src/main/java/org/easyrules/samples/spring/Launcher.java create mode 100644 easyrules-samples/src/main/resources/org/easyrules/samples/spring/application-context.xml create mode 100644 site/tutorials/spring-tutorial.md create mode 100644 site/user-guide/embedding-rules-engine.md diff --git a/easyrules-samples/pom.xml b/easyrules-samples/pom.xml index a93b9c9..cd373fe 100644 --- a/easyrules-samples/pom.xml +++ b/easyrules-samples/pom.xml @@ -64,6 +64,17 @@ easyrules-quartz + + org.easyrules + easyrules-spring + + + + org.springframework + spring-context-support + 3.2.13.RELEASE + + @@ -155,6 +166,28 @@ + + runSpringTutorial + + exec:java + + + org.codehaus.mojo + exec-maven-plugin + 1.3 + + org.easyrules.samples.spring.Launcher + + + java.util.logging.SimpleFormatter.format + [%1$tc] %4$s: %5$s%n + + + + + + + diff --git a/easyrules-samples/src/main/java/org/easyrules/samples/spring/DummyRule.java b/easyrules-samples/src/main/java/org/easyrules/samples/spring/DummyRule.java new file mode 100644 index 0000000..92e94bb --- /dev/null +++ b/easyrules-samples/src/main/java/org/easyrules/samples/spring/DummyRule.java @@ -0,0 +1,19 @@ +package org.easyrules.samples.spring; + +import org.easyrules.annotation.Action; +import org.easyrules.annotation.Condition; +import org.easyrules.annotation.Rule; + +@Rule(name = "dummy rule") +public class DummyRule { + + @Condition + public boolean when() { + return true; + } + + @Action + public void then(){ + System.out.println("Hey, I'm managed by Spring"); + } +} diff --git a/easyrules-samples/src/main/java/org/easyrules/samples/spring/Launcher.java b/easyrules-samples/src/main/java/org/easyrules/samples/spring/Launcher.java new file mode 100644 index 0000000..6ba260e --- /dev/null +++ b/easyrules-samples/src/main/java/org/easyrules/samples/spring/Launcher.java @@ -0,0 +1,45 @@ +/* + * The MIT License + * + * Copyright (c) 2014, Mahmoud Ben Hassine (mahmoud@benhassine.fr) + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in + * all copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + * THE SOFTWARE. + */ + +package org.easyrules.samples.spring; + +import org.easyrules.api.RulesEngine; +import org.springframework.context.ApplicationContext; +import org.springframework.context.support.ClassPathXmlApplicationContext; + +/** + * Main class to run the Spring tutorial. + * + * @author Mahmoud Ben Hassine (mahmoud@benhassine.fr) + */ +public class Launcher { + + public static void main(String[] args) throws Exception { + ApplicationContext context = new ClassPathXmlApplicationContext("org/easyrules/samples/spring/application-context.xml"); + RulesEngine rulesEngine = (RulesEngine) context.getBean("rulesEngine"); + + rulesEngine.fireRules(); + } + +} diff --git a/easyrules-samples/src/main/resources/org/easyrules/samples/spring/application-context.xml b/easyrules-samples/src/main/resources/org/easyrules/samples/spring/application-context.xml new file mode 100644 index 0000000..5e19f32 --- /dev/null +++ b/easyrules-samples/src/main/resources/org/easyrules/samples/spring/application-context.xml @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/pom.xml b/pom.xml index 07ee031..4d774af 100644 --- a/pom.xml +++ b/pom.xml @@ -98,6 +98,12 @@ ${project.version} + + org.easyrules + easyrules-spring + ${project.version} + + junit junit diff --git a/site/_includes/docs_contents.html b/site/_includes/docs_contents.html index cdd3eeb..2c969fc 100644 --- a/site/_includes/docs_contents.html +++ b/site/_includes/docs_contents.html @@ -28,6 +28,9 @@
  • Scheduling rules engine
    • +
  • + Embedding rules engine +

    • Tutorials

    @@ -44,6 +47,9 @@
  • Engine scheduler
    • +
  • + Spring tutorial +
    • diff --git a/site/get-involved/release-notes.html b/site/get-involved/release-notes.html index 0d42418..2236a07 100644 --- a/site/get-involved/release-notes.html +++ b/site/get-involved/release-notes.html @@ -1,7 +1,7 @@ --- layout: news title: "Release notes" -prev_section: tutorials/scheduling-engine +prev_section: tutorials/spring-tutorial doc: true --- diff --git a/site/tutorials/scheduling-engine.md b/site/tutorials/scheduling-engine.md index f48649b..3047878 100644 --- a/site/tutorials/scheduling-engine.md +++ b/site/tutorials/scheduling-engine.md @@ -3,7 +3,7 @@ layout: docs title: Engine scheduler header: Engine scheduler prev_section: tutorials/dynamic-configuration -next_section: get-involved/release-notes +next_section: tutorials/spring-tutorial doc: true --- diff --git a/site/tutorials/spring-tutorial.md b/site/tutorials/spring-tutorial.md new file mode 100644 index 0000000..cbfca3c --- /dev/null +++ b/site/tutorials/spring-tutorial.md @@ -0,0 +1,99 @@ +--- +layout: docs +title: Using Easy Rules with Spring +header: Using Easy Rules with Spring +prev_section: tutorials/scheduling-engine +next_section: get-involved/release-notes +doc: true +--- + +In this tutorial, you will learn how to use Easy Rules embedded in a Spring container. + +You will create a dummy rule and a rules engine and configure them as Spring beans. So let's get started. + +First you need to add the following dependency to your **_pom.xml_**: + +```xml + + org.easyrules + easyrules-spring + {{site.version}} + +``` + +Then, let's create the dummy rule: + +```java +@Rule(name = "dummy rule") +public class DummyRule { + + @Condition + public boolean when() { + return true; + } + + @Action + public void then(){ + System.out.println("Hey, I'm managed by Spring"); + } +} +``` + +Now, we we can use the `RulesEngineFactoryBean` to configure a rules engine and register the dummy rule: + +```xml + + + + + + + + + + + + + + + + +``` + +Finally, we can get the rules engine from the Spring context and fire rules: + +```java +public class Launcher { + + public static void main(String[] args) throws Exception { + ApplicationContext context = new ClassPathXmlApplicationContext("org/easyrules/samples/spring/application-context.xml"); + RulesEngine rulesEngine = (RulesEngine) context.getBean("rulesEngine"); + + rulesEngine.fireRules(); + } + +} +``` + +That's all. To run the tutorial, you can follow these instructions from the root directory of Easy Rules: + +{% highlight bash %} +$ mvn install +$ cd easyrules-samples +$ mvn exec:java -P runSpringTutorial +{% endhighlight %} + +You would get the following output: + +``` +INFO: Rule priority threshold: 2,147,483,647 +INFO: Skip on first applied rule: false +INFO: Skip on first failed rule: false +INFO: Rule 'dummy rule' triggered. +Hey, I'm managed by Spring +INFO: Rule 'dummy rule' performed successfully. +``` + diff --git a/site/user-guide/embedding-rules-engine.md b/site/user-guide/embedding-rules-engine.md new file mode 100644 index 0000000..794c693 --- /dev/null +++ b/site/user-guide/embedding-rules-engine.md @@ -0,0 +1,85 @@ +--- +layout: docs +title: Embedding rules engine +header: Embedding rules engine +prev_section: user-guide/scheduling-rules-engine +next_section: tutorials/hello-world +doc: true +--- + +Easy Rules is a lightweight library that can be used in a standalone Java application or embedded in a web server or a DI container. + +As of version {{ site.version }}, Easy Rules provides support for Spring. +Support for other DI containers will be added in future versions. + +In this section, you will learn how to configure rules and rules engine as Spring beans. +First you need to add the following dependency to your **_pom.xml_**: + +```xml + + org.easyrules + easyrules-spring + {{site.version}} + +``` + +Then, you can configure your rules and the rules engine as follows: + +```xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + +``` + +The `RulesEngineFactoryBean` is responsible for creating rules engine instances. +As you can see, this factory bean is the main entry point to configure: + +* Rules +* Rules listeners +* And engine parameters (priority threshold, skipOnFirstAppliedRule, silentMode, etc) + +To get the engine and fires rules, you can use the following snippet: + +```java +ApplicationContext context = new ClassPathXmlApplicationContext("application-context.xml"); +RulesEngine rulesEngine = (RulesEngine) context.getBean("rulesEngine"); + +rulesEngine.fireRules(); +``` + +
    +
    Hint:
    +

    The main advantage of using Easy Rules with Spring is the ability to register/unregister rules through the Xml configuration + without recompiling your application.

    +
    + + +You can find a complete tutorial on how to use Easy Rules with Spring [here]({{site.url}}/tutorials/spring-tutorial.html). \ No newline at end of file diff --git a/site/user-guide/scheduling-rules-engine.md b/site/user-guide/scheduling-rules-engine.md index 722c921..51e62f0 100644 --- a/site/user-guide/scheduling-rules-engine.md +++ b/site/user-guide/scheduling-rules-engine.md @@ -3,7 +3,7 @@ layout: docs title: Scheduling rules engine header: Scheduling rules engine prev_section: user-guide/managing-rules -next_section: tutorials/hello-world +next_section: user-guide/embedding-rules-engine doc: true --- @@ -12,13 +12,11 @@ Easy Rules provides APIs to schedule a rules engine using the popular Java sched To schedule a rules engine instance, first you need to add the following dependency to your **_pom.xml_**: ```xml - - - org.easyrules - easyrules-quartz - {{site.version}} - - + + org.easyrules + easyrules-quartz + {{site.version}} + ``` Then, you can create a `RulesEngineScheduler` as follows: