Thursday, January 07, 2010

Writing Business Rules in WSO2 Carbon Platform

If you want to write rules in a Java program you have lot of choices. You can use a third party library like Drools or use the JAVA built-in JSR-94 reference implementation. In WSO2 Carbon, there is a component that abstract the behaviour of different rule engine and give you a unified API. Currently it has plugged into Drools and JAVA built-in JSR-94 implementation.

The rule component in WSO2 Carbon platform mainly used by WSO2 ESB product to mediate messages according to the given business rules. But the component is written to facilitate any requirement of using business rules in WSO2 Carbon platform. I had such a requirement in past few days and manage to use the rule component easily with the help of the component author, So I thought it is worth sharing my experience in here.

Here You will be preparing the following stuff.

1. Rule configuration -

We can use this to provide the information about the rule implementation we are going to use, the rules (You can write rules inline or provide a reference to an external file) and the input and output adapter information.
<configuration xmlns="">
<executionSet uri="simpleItemRuleXML">
<source key="file:src/test/resources/rules/simple-rules.drl"/>

<!-- <source>

rule InvokeABC
// rules inbuilt to the rule conf

</source> -->
<property name="source" value="drl"/>

<session type="stateless"/>
<input name="facts" type="itemData" key="dataContext"></input>

<output name="results" type="itemData" key="dataContext"></output>

2. The Rules  -

You can write rules inline in the above configuration or put it in a file and refer it from a key which can be refered from the ResourceHelper (described below).
import java.util.Calendar;

rule YearEndDiscount
$item : org.test.pojo.SimpleItem(price > 100 )


Calendar calendar = Calendar.getInstance();
if (calendar.get(Calendar.MONTH) == Calendar.JANUARY) {

$item.setPrice($item.getPrice() * 80/100);


3. Data Context -

The context object that can be used to feed and retrieve data from and to rule engine. Here is the data context for my application.
public class SimpleDataContext {

public List<NameValuePair> getInput() {

// in reality the data will be retrieve from a database or some datasource
List<NameValuePair> itemPairList = new ArrayList<NameValuePair>();
SimpleItem item1 = new SimpleItem();
itemPairList.add(new NameValuePair(item1.getName(), item1));

SimpleItem item2 = new SimpleItem();
itemPairList.add(new NameValuePair(item2.getName(), item2));

SimpleItem item3 = new SimpleItem();
itemPairList.add(new NameValuePair(item3.getName(), item3));

return itemPairList;

public void setResult(Object result) {

if (!(result instanceof SimpleItem)) {
System.out.println("it is not a SimpleItem");

SimpleItem item = (SimpleItem)result;
System.out.println("Item: " + item.getName() + ", Price: " + item.getPrice());


And the Item I'm going to manipulate using rule is a simple bean like this,
public class SimpleItem {
String name;
int price;
public String getName() {

return name;

public void setName(String name) { = name;

public int getPrice() {

return price;

public void setPrice(int price) {

this.price = price;

4. Data Adapter

You have to adapt the input and output with the rule engine. Mostly here you only have to wrap the data context. The advantage of having the data adapter is, a data adapter always associated with a input/output type. So in the rule configuration I can provide the type for the input and output. If you see my rule configuration above, you see the input/output type is marked as "ItemData". Here is my custom data adapter that is associated with the "itemData" type.
public class SimpleDataAdapter implements
ResourceAdapter, InputAdaptable, OutputAdaptable {

// the type associated with the adapter
private final static String TYPE = "itemData";
public String getType() {

return TYPE;

public Object adaptInput(ResourceDescription resourceDescription, Object tobeadapted) {

if (!(tobeadapted instanceof SimpleDataContext)) {
return null;

SimpleDataContext dataContext = (SimpleDataContext)tobeadapted;
return dataContext.getInput();

public boolean adaptOutput(ResourceDescription description,
Object value,
Object context,
ResourceHelper resourceHelper) {

if (!(context instanceof SimpleDataContext)) {
return false;

return true;

public boolean canAdapt(ResourceDescription description, Object ouptput) {
String key = description.getKey();
return key != null && !"".equals(key);


5. Resource Helper

Resource Helper will map the keys refered from the configuration to JAVA objects. This is mostly used in mediation rule configurations which can extract the message data using a key or an xpath. In this example, we don't have much keys refering from the configuration only the rule file and the data context.
public class SimpleResourceHelper extends ResourceHelper {

public ReturnValue findByKey(String key, Object source, Object defaultValue) {

if (!(source instanceof SimpleDataContext)) {
return new ReturnValue(defaultValue);

SimpleDataContext dataContext = (SimpleDataContext)source;
if (key.startsWith("file:")) {

String filename = key.substring("file:".length());
try {

BufferedInputStream in = new BufferedInputStream(new FileInputStream(filename));
return new ReturnValue(in);
} catch (Exception e) {

return new ReturnValue(defaultValue);
if (key.startsWith("dataContext")) {

return new ReturnValue(dataContext);
return new ReturnValue(defaultValue);

// there are few more methods to be implemented, which can just leave not implemented for this example

That is all the accessories. Now you will be able to write the rule engine execution code.
File ruleConfigFile = new File(ruleConfigFilename);
XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(ruleConfigFile));

//create the builder
StAXOMBuilder builder = new StAXOMBuilder(parser);
//get the root element (in this case the envelope)

OMElement ruleConfig = builder.getDocumentElement();
EngineConfiguration configuration =
new EngineConfigurationFactory().create(ruleConfig, new AXIOMXPathFactory());

engineController = new EngineController(configuration, new SimpleResourceHelper());
final ResourceAdapterFactory factory = ResourceAdapterFactory.getInstance();

ResourceAdapter adapter = new SimpleDataAdapter();
String adapterType = adapter.getType();
if (!factory.containsResourceAdapter(adapterType)) {


SimpleDataContext simpleContext = new SimpleDataContext();

if (!engineController.isInitialized()) {


if (engineController.isInitialized()) {
engineController.execute(simpleContext, simpleContext);



dushshantha said...

This is cool. Thanks for Sharing. Im working with comercial rules engines these days. Just thought of implementing one of the simple scenarios on Carbon. What is this particular component? Is it WSO2 ESB?

dimuthu said...

Hi Dushshantha,
Nice to know this was useful:). It is a carbon component that is by default packed in WSO2 ESB product. It is in carbon-components/rule ( You will be able to implement the scenarios you mentioned as carbon components and run on top of the WSO2 Carbon. (The rule component is not a core component. So it is not available in carbon by default, although it is in WSO2 ESB by default. So you need to add the rule component along with the components for the scenarios to WSO2 Carbon.


Silas Thomeczek said...

Easily, the article is truly the freshest on this noteworthy topic. I fit in with your conclusions and will thirstily look forward for your future updates. Saying thanks will not just be adequate, for the phenomenal lucidity within your writing. I am going to at once grab your rss feed to stay privy of any updates. Excellent work and very much achievement inside your business dealings!