jsRules
Simple JSON-based Rules Engine
Introduction
jsRules is a "no frills" rules engine that allows for quick and easy rules resolution all configurable through JSON files.
Why a rules engine?
A rules engine seperates your business logic from your application logic, making it possible to changes those rules without updating code or even redeploying your app. jsRules uses a straight-forward JSON implementation that could easily be edited via a web page, mobile app, or even by hand...keeping those rules in the hands of the people who understand them, without having to engage developers for simple changes.
How do I implement it?
-
Import the JAR into any Java application
-
Create your rules as JSON and put them on the classpath.
-
Put the parameters needed to resolve the rules into a Map<String, Object>
-
Finally, call the rules engine using just one line of code:
JsRules.getInstance().execute("DrinkingAge");
Terminology
- Rule -- a rule is the building block for the rules engine. It performs very simple calculations using a left parameter, a right parameter, and an operator.
- Ruleset -- a ruleset is a set of rules executed in order. This is what is invoked via the JsRules execute() method.
- Ruleset List -- a ruleset list is a set of rulesets executed in order. Ruleset Lists are also a type of ruleset, so you can stack them on top of each other in any configuration needed, allowing your rules to be as simple or complex as necessary.
Rules
Rules consist of the following components:
- Rule Name -- a unique identifier for the rule. It should match the name of the json file containing it.
- Left Parameter -- the name and class of the left parameter.
- Operator -- denotes the operation to be performed between the left parameter and the right parameter.
- Right Parameter -- the name and class of the right parameter. Optionally, may contain a static value that will always be used for comparison.
- Response -- the value and class of the response. This will be returned if the rule evaluates as true. Otherwise, null will be returned.
Classes
The following classes are currently available for use in both the parameters and the response:
- Boolean
- Double
- Long
- String
- NumberSet
- DateTime -- backed by Joda Time, expected format "YYYY-MM-ddTHH:mm:ss.SSS-ZZ:ZZ"
Operators
The following operators are available for use in rules:
- GT -- greater than (works for numbers or dates only)
- LT -- less than (works for numbers or dates only)
- GTE -- greater than or equal (works for numbers or dates only)
- LTE -- less than or equal (works for numbers or dates only)
- EQ -- equals
- NE -- not equals
- IN -- in (left parameter is a number or date, right parameter is a set of numbers or dates)
- NOT_IN -- not in (inclusive: left parameter is a number or date, right parameter is a set of numbers or dates)
- BETWEEN -- between (inclusive: left parameter is a number or date, right parameter is a set of two numbers or dates)
- NOT_BETWEEN -- not between (left parameter is a number or date, right parameter is a set of two numbers or dates)
Sample Rule json
This rule is named "GreaterThan10" and evaluates whether the left parameter is greater than 10. If the rule evaluates true, it will return a Boolean set to true.
{
"ruleName": "GreaterThan10",
"leftParamConfig": {
"parameterName": "left",
"parameterClass": "Long"
},
"operator": "GT",
"rightParamConfig": {
"parameterName": "right",
"parameterClass": "Long",
"parameterStaticValue": "10"
},
"responseConfig": {
"response": "true",
"responseClass": "Boolean"
}
}
Rulesets
A ruleset evaluates several rules in sequence, and consists of the following components:
- Ruleset Name -- a unique identifier for the ruleset. It should match the name of the json file containing it.
- Ruleset Type -- the type of ruleset we are executing ("AllTrue" or "FirstTrue")
- Response -- the value and class of the response that will be sent if the ruleset evaluates as true (not applicable to "FirstTrue" type)
- Components -- a list of rules to be executed, by name, in the order they should be executed
Ruleset Types
- AllTrue -- if all the rules evaluate as true, returns the given response
- FirstTrue -- executes all the rules in order, and returns the response of the first one that evaluates as true
Sample Ruleset Json
{
"rulesetName": "InventoryRuleset",
"rulesetType": "AllTrue",
"responseConfig": {
"response": "Item is in stock",
"responseClass": "String"
},
"components": [
"ItemIsCarriedRule",
"MoreThanZeroStocked"
]
}
Ruleset List
A ruleset list is a type of ruleset that executes a series of rulesets in order (as opposed to a series of rules). Its format is exactly the same as any other ruleset, the only difference is the type and the components.
Ruleset List Types
- AllTrueList -- if all the rulesets evaluate as true, returns the given response
- FirstTrueList -- executes all the rulesets in order, and returns the response of the first one that evaluates as true
Sample Ruleset List Json
{
"rulesetName": "CanPurchaseRulesetList",
"rulesetType": "AllTrueList",
"responseConfig": {
"response": "Customer can purchase something",
"responseClass": "String"
},
"components": [
"InBudgetRuleset",
"InventoryRuleset"
]
}
Future Features
This library is very much in its infancy. Here are some features under consideration for future releases:
- Ruleset Chaining -- add the response from one ruleset to the parameters so that it can be used in downstream rule execution
- Term Resolving -- add the ability to resolve parameters that are required by not provided
- Improved Caching Options
- NoSQL Integration
- More Classes
- More Operators
- Custom Classes and Operators
- And More!