Introductory tutorial on using the Liferay 6 Drools Web Portlet

In this blog entry I provide an introduction on how you can start to leverage a business rules engine in your portal implementation. Liferay Enterprise Edition 6 comes with a drools web portlet that allows you to use the Drools rule engine with minimal effort, and this blog entry will help you get going.

Problem Domain
Enterprise applications usually have multiple layers, one of which is the business layer. The requirements for the business logic layer change more often than the other layers. The traditional way to implement business rules/logic in JEE or JSE application is to write java codes that realizes the required business rules/logic. In most cases, this code’s intricacy and complexity makes maintenance of business logic a daunting tasks. Moreover, changes to the business rules incurs recompilation and redeployment costs.

Solution
The solution is to use a rules engine to realize business rules.  This is assuming the application being built is complex enough to justify the use of a rules engine.  Rules engine allows domain experts to modify business rules without developer intervention. In the context of liferay portlet development, drools web plugin enables liferay portlet developer  to take advantage of drools as a rules engine.

What is drools web portlet?
Drools web portlet is a plugin provided with Liferay EE 6.0.  It acts as a proxy for drools and exposes it to liferay as a utility.  This enables all portlets within liferay portal to utilize drools without importing drools libraries and without directly executing drools code.  Thus, the portlet will not be cluttered with jars just to support drools.

What to expect when deployed?
When deployed in liferay there will be no visible changes. The plugin is only an engine that implements message proxies in com.liferay.portal.kernel.bi.rules.RulesEngine. Acting as a proxy, it makes the actual calls to the drools libraries. This is then exposed to the portlet developer using com.liferay.portal.kernel.bi.rules.RulesEngineUtil. Thus, allowing portlet developers to utilize drools without importing drools libraries. RulesEngine and RulesEngineUtil are located in portal-server.jar

Sample Usage
Assume Shipping Rate Rule:

package com.xtivia.shoppingcart

rule “Free Shipping For Orders Greater Than $300”

when

shoppingCart: ShoppingCart( amount > 300, shippingCost > 0)

then

shoppingCart.setShippingCost(0);

end

Step 1: Create a ResourceRetriever which points to an xml file that contains details on where to get the rules such as the location of BRMS server and credentials to use to access the server.  In this example, changeset.xml.

RulesResourceRetriever resourceRetriever = null;
 

final InputStream is = getClass().getClassLoader().getResourceAsStream("changeset.xml");
 resourceRetriever = new RulesResourceRetriever(RulesLanguage.DROOLS_CHANGE_SET.name());
 resourceRetriever.addResourceRetriever(
 

new ResourceRetriever() {
 

public InputStream getInputStream() {
 

return is;
 

}
 

}
 

);

Content of changeset.xml
 <change-set>
 <add>
 

<resource source='http://brms.www.xtivia.com/shippingCalculator/PKG/LATEST’
      type='PKG' basicAuthentication='enabled'
      username='admin'
      password='admin' />
 

</add>
 </change-set>

Step 2: Using the ResourceRetriever retrieve the rules from the stream into memory by executing the code below:

RulesEngineUtil.add("shoppingCart", resourceRetriever, getClass().getClassLoader());

Note: “shoppingCart” is some arbitrary string for referencing this package/rules in memory.

Step 3: Create all the Facts where the rules will be applied to.
Let’s assume at this point we have a bean called shoppingCart, which contains shopping cart details as well as shipping charges.  Assume, total amount > $300 and shipping cost > 0 for the shoppingCart bean.

List<Fact<?>> factList = new ArrayList<Fact<?>>();
 

factList.add(new Fact<ShoppingCart>("shoppingCart", shoppingCart));

Step 4: Execute the rules against the Facts from Step 3 by executing the code below.

RulesEngineUtil.execute("shoppingCart", factList);

Result: After the execution, the shoppingCart bean will be modified by the rule to reflect the free shipping by setting the shippingCost to 0 if the total amount is greater than $300.  See sample rule above.

In the future, if the business rule requires free shipping to take effect if total cost is greater than $500 then the domain expert may change the rule by changing the value in the rule without developer intervention and without recompiling the code.

Summary
In developing an enterprise application one should consider using a business rule engine, especially when business logic changes regularly.  Drools web portlet allows portlet developers to utilize drools seamlessly with liferay EE 6.