README.textile

   1 h1. reguloj "!https://secure.travis-ci.org/sebhoss/reguloj.png!":http://travis-ci.org/sebhoss/reguloj "!https://www.ohloh.net/p/reguloj/widgets/project_thin_badge.gif!":https://www.ohloh.net/p/reguloj/
   2
   3
   4 p. *reguloj* is a small and lightweight Java rule engine. It is suitable for mobile applications running "Android":http://www.android.com/ and/or other restricted environments such as "GWT":http://www.gwtproject.org/.
   5
   6 h2. Usage
   7
   8 h3. Creating rule engines
   9
  10 p. A rule engine evaluates a set of rules in a specific context. The @RuleEngines@ utility class offers to build 3 different rule engines:
  11
  12 bc.. // All rules will be evaluated indefinitely until no further rule fires.
  13 final RuleEngine<CONTEXT> chained = RuleEngines.chained();
  14
  15 // All rules will be evaluated, but only a maximum number of 5 times.
  16 final RuleEngine<CONTEXT> limited = RuleEngines.limited(5);
  17
  18 // Evaluates all rules, stops after the first one that fires.
  19 final RuleEngine<CONTEXT> firstWins = RuleEngines.firstWins();
  20
  21 p. If custom inference behavior is required, subclass @AbstractRuleEngine@ and implement the infer() method. The following code example shows how to work with rule engines:
  22
  23 bc.. RuleEngine<CONTEXT> engine = ...;
  24 Iterable<Rule<CONTEXT>> rules = ...;
  25 CONTEXT context = ...;
  26
  27 // true if at least one rule can fired.
  28 engine.analyze(rules, context);
  29
  30 // perform conclusions of those rules that fired.
  31 engine.infer(rules, context);
  32
  33 h3. Creating rules
  34
  35 p. A "rule":https://github.com/sebhoss/reguloj/blob/master/src/main/java/com/github/sebhoss/reguloj/Rule.java has a (unique) name and runs in a given context. Additionally it can be checked whether a rule fires in a given context.
  36
  37 p. Either implement the @Rule@ interface yourself and or use the supplied rule implementation and builder. A standard rule is composed of a "predicate"::http://guava-libraries.googlecode.com/svn/trunk/javadoc/com/google/common/base/Predicate.html and a "conclusion":https://github.com/sebhoss/reguloj/blob/master/src/main/java/com/github/sebhoss/reguloj/Conclusion.java. Both interfaces require you to implement only a single method and do not restrict you in any way. Complex rules can be created by grouping or chaining predicates/conclusions together with the help of several utility methods. The following example creates a rule composed of 2 predicates and 2 conclusions while using static imports:
  38
  39 bc..
  40 final Rule<CONTEXT> rule = rule().called(name)
  41                         .when(and(predicate1, predicate2))
  42                         .then(conclude(conclusion1, conclusion2))
  43
  44 // true if the rule would fire in the given context, e.g. the above predicate is true.
  45 rule.fires(context);
  46
  47 // true if the rule changed the state of the given context, e.g. the above conclusion applies.
  48 rule.run(context);
  49
  50 p. Using Java 8 lambdas is possible as well:
  51
  52 bc.
  53 final Rule<CONTEXT> rule = rule().called(name)
  54                         .when(context -> context.check())
  55                         .then(context -> context.action())
  56
  57
  58 h3. Creating an inference context
  59
  60 p. An inference "context":https://github.com/sebhoss/reguloj/blob/master/src/main/java/com/github/sebhoss/reguloj/Context.java contains information needed by predicates and/or conclusions. This project supplies a simple implementation of the @Context@ interface called @BaseContext@. Subclass @BaseContext@ in case your rules need extra information. The API acknowledges this by using @<CONTEXT extends Context<?>>@ as type parameter for all methods which expect an @Context@. See item 28 in Effective Java for more details.
  61
  62 h3. Integration
  63
  64 p. To use reguloj just declare the following dependency inside your _POM_:
  65
  66 bc.
  67 <dependency>
  68   <groupId>com.github.sebhoss</groupId>
  69   <artifactId>reguloj</artifactId>
  70   <version>${version.reguloj}</version>
  71 </dependency>
  72
  73 p. Replace @${version.reguloj}@ with the "latest release":http://search.maven.org/#search%7Cga%7C1%7Cg%3Acom.github.sebhoss%20a%3Areguloj
  74
  75 h2. Development
  76
  77 h3. License
  78
  79 p. This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See "http://sam.zoy.org/wtfpl/COPYING":http://sam.zoy.org/wtfpl/COPYING for more details.
  80
  81 h3. Setup
  82
  83 p. reguloj is using "Maven":http://maven.apache.org/, "Eclipse":http://eclipse.org/ and "Git":http://git-scm.com/ as the main development tools. To build the project yourself just download & install at least Maven 3.0 and call *mvn install* inside the project folder. Maven should then proceed to clean, test, build, package and install the business rules engine.
  84
  85 h3. Versioning
  86
  87 p. reguloj follows the "semantic versioning":http://semver.org/ guidelines.