Introducing camel-drools component

Introduction In this post I’ll try to introduce

Apache Camel component for Drools library – a great an widely used Business Rules Management System. When we decided to use Drools 5 inside Servicemix for some big project, it turned out that there is no production-ready solution that will meet out requirements. The servicemix-drools component is lacking several very important features, eg:
* StatefulSession database persistence for long-running processes,
* support for Complex Event Processing (event-based rules),
* Apache Camel based deployment to ease rules consequence processing,
* Support for Drools unit testing framework. To satisfy those requirements, Maciek Próchniak created a set of utility classes, which helped us run Drools inside Camel route. Starting from this codebase, we did some refactoring, add few new features (eg. pluggable object persistance) and released camel-drools component on TouK Open Source Projects forge.

Example To summarize key features and show how to use camel-drools component, let’s try to implement an example taken from Drools Flow documentation:

There is kind-of ‘process’ where first Task1 and Task2 are created and can be executed in parallel. Task3 needs to be executed after completion of both Task1 and Task2.

Implementation The class Task have 2 fields, a

name and completed flag, we also need an id for session serialization:

public class Task implements Serializable {
    private static final long serialVersionUID = -2964477958089238715L;    
    private String name;
    private boolean completed;

    public Task(String name) {
        this(name, false);
    }

    public Task(String name, boolean completed) {
        this.name = name;
        this.completed = completed;
    }

    public String getName() {
        return name;
    }

    public boolean isCompleted() {
        return completed;
    }

    public long getId() {
        return name.hashCode();
    }
}

We also define another class representing the state of process, needed to fire rules in correct order. Using that model, we now can implement our ruleset, defined in

task.drl file:

import org.apache.camel.component.drools.stateful.*

global org.apache.camel.component.drools.CamelDroolsHelper helper

rule "init"
salience 100
    when
        $s : State(name=="start")
    then
        insert(new Task("Task1"));
        insert(new Task("Task2"));
        retract($s);
end

rule "all tasks completed"
    when
        not(exists Task(completed==false))
        not(exists State(name=="end"))
    then
        insert(new Task("Task3"));
end

rule "Task3 completed"
salience 30
    when 
        Task(name=="Task3", completed==true)
    then
        insert(new State("end"));
        helper.send("direct:completed", "completed");
end

In first rule – “init” we insert two tasks and then retract state object from the session to avoid recursive execution of that rule. Rule “all tasks completed” shows the power of Drools – we just declare that this rule is fired when “there are no incompleted tasks” and don’t have to specify which tasks. So this shows rather ‘declarative’ than ‘imperative’ way of development – we have much more expressiveness than just step-by-step actions which lead to some situation. The

CamelDroolsHelper is a wrapper for ProducerTemplate and can be used to send some message trough another Camel route as consequence of a rule. But how are Tasks mark as completed in Drools session? The idea is to expose session through Camel endpoint to allow insert or update objects, which are passed as body of exchanges:

public class TaskRouteBuilder extends RouteBuilder {
    @Override
    public void configure() throws Exception {
        from("direct:drools")
            .setHeader("drools.key", constant(new MultiKey(new String[] {
                "process-1"
            })))
            .to("drools:task.drl?stateful=true");
        from("direct:completed").to("log:test");
    }
}

The Drools endpoint is described by

"drools:task.drl?stateful=true" URI. It loads definition of rules from task.drl file and runs endpoint in stateful mode (described next paragraph). When object is passed to this endpoint, it is inserted (or updated) to session and fireAllRules() method is called. Another important thing is “drools.key” header – it is used to distinguish sessions between “processes”. E.g. when we have some customer-oriented rules, we want to group facts and events in session per customer – by some customer id. When the “drools.key” is set to that id, sessions for different customers could be found and saved separately.

Stateful session persistence Camel-drools component can be used in two modes:

stateful *and *stateless. The main difference between those is session persistence – only in stateful mode session is stored in database. So long duration event rules are correctly handled only in this mode – and this is what we used in this example. Let’s look at Spring context definition:

task_id

As you can see, there are some requirements for database objects to handle session persistence correctly – two tables: one for KnowlegdeStatefulSession and one for objects (facts and events) persistence. You can name them freely, just provide those names to

sessionTable and objectTable properties of sessionDAO. A sequence for id generation is also needed.

Route and rules testing Here is example test for TaskRouteBuilder:

@SuppressWarnings("unchecked")
public class TaskRouteBuilderTest extends TaskRouteBuilder {

    DefaultCamelContext ctx;
    ProducerTemplate tpl;
    MockSessionDAO dao;

    @Before
    public void makeContext() throws Exception {
        ctx = new DefaultCamelContext();
        ctx.addComponent("drools", new DroolsComponent(ctx));
        ApplicationContext appCtx = new ClassPathXmlApplicationContext(
            new String[] {
                "camel-drools-context.xml",
                "mock-dao-context.xml"
            });
        dao = (MockSessionDAO) appCtx.getBean("sessionDAO");
        ctx.setRegistry(new ApplicationContextRegistry(appCtx));
        ctx.addRoutes(this);
        ctx.addRoutes(new RouteBuilder() {
            @Override
            public void configure() throws Exception {
                from("direct:completed").to("mock:test");
            }
        });
        ctx.start();
        tpl = ctx.createProducerTemplate();
    }

    @Test
    public void testUpdate() throws Exception {
        Endpoint endpoint = ctx.getEndpoint("direct:drools");
        tpl.requestBody(endpoint, new State("start"));
        SessionWithIdentifier session = dao.getSession();
        Assert.assertEquals(2, session.getSession().getFactHandles().size());
        tpl.requestBody(endpoint, new Task("Task1", true));
        tpl.requestBody(endpoint, new Task("Task2", true));
        Assert.assertEquals(3, session.getSession().getFactHandles().size());
        tpl.requestBody(endpoint, new Task("Task3", true));

        MockEndpoint mock = MockEndpoint.resolve(ctx, "mock:test");
        mock.expectedMessageCount(1);
        mock.setResultWaitTime(5000 L);
        mock.assertIsSatisfied();
    }
}

In setup method some required initialization is done – camel-drools-context.xml file is loaded and MockSessionDao created. The test first starts process by passing State object with “start” name to Drools session through Camel route. This should add Task1 and Task2 to session – and it’s tested by counting the factHadles in session. Next, Task1 and Task2 are updated by making them completed, which should result in Task3 present in session – another factHandle. Last step is to complete Task3 and check that last rule is executed by assertions on MockEndpoint. You can download source code for this example and whole component from

here – this is branch for Camel 1.x version, which we use in our project.

You May Also Like

Grails session timeout without XML

This article shows clean, non hacky way of configuring featureful event listeners for Grails application servlet context. Feat. HttpSessionListener as a Spring bean example with session timeout depending on whether user account is premium or not.

Common approaches

Speaking of session timeout config in Grails, a default approach is to install templates with a command. This way we got direct access to web.xml file. Also more unnecessary files are created. Despite that unnecessary files are unnecessary, we should also remember some other common knowledge: XML is not for humans.

Another, a bit more hacky, way is to create mysterious scripts/_Events.groovy file. Inside of which, by using not less enigmatic closure: eventWebXmlEnd = { filename -> ... }we can parse and hack into web.xml with a help of XmlSlurper.
Even though lot of Grails plugins do it similar way, still it’s not really straightforward, is it? Besides, where’s the IDE support? Hello!?

Examples of both above ways can be seen on StackOverflow.

Simpler and cleaner way

By adding just a single line to the already generated init closure we have it done:
class BootStrap {

def init = { servletContext ->
servletContext.addListener(OurListenerClass)
}
}

Allrighty, this is enough to avoid XML. Sweets are served after the main course though :)

Listener as a Spring bean

Let us assume we have a requirement. Set a longer session timeout for premium user account.
Users are authenticated upon session creation through SSO.

To easy meet the requirements just instantiate the CustomTimeoutSessionListener as Spring bean at resources.groovy. We also going to need some source of the user custom session timeout. Let say a ConfigService.
beans = {    
customTimeoutSessionListener(CustomTimeoutSessionListener) {
configService = ref('configService')
}
}

With such approach BootStrap.groovy has to by slightly modified. To keep control on listener instantation, instead of passing listener class type, Spring bean is injected by Grails and the instance passed:
class BootStrap {

def customTimeoutSessionListener

def init = { servletContext ->
servletContext.addListener(customTimeoutSessionListener)
}
}

An example CustomTimeoutSessionListener implementation can look like:
import javax.servlet.http.HttpSessionEvent    
import javax.servlet.http.HttpSessionListener
import your.app.ConfigService

class CustomTimeoutSessionListener implements HttpSessionListener {

ConfigService configService

@Override
void sessionCreated(HttpSessionEvent httpSessionEvent) {
httpSessionEvent.session.maxInactiveInterval = configService.sessionTimeoutSeconds
}

@Override
void sessionDestroyed(HttpSessionEvent httpSessionEvent) { /* nothing to implement */ }
}
Having at hand all power of the Spring IoC this is surely a good place to load some persisted user’s account stuff into the session or to notify any other adequate bean about user presence.

Wait, what about the user context?

Honest answer is: that depends on your case. Yet here’s an example of getSessionTimeoutMinutes() implementation using Spring Security:
import org.springframework.security.core.context.SecurityContextHolder    

class ConfigService {

static final int 3H = 3 * 60 * 60
static final int QUARTER = 15 * 60

int getSessionTimeoutSeconds() {

String username = SecurityContextHolder.context?.authentication?.principal
def account = Account.findByUsername(username)

return account?.premium ? 3H : QUARTER
}
}
This example is simplified. Does not contain much of defensive programming. Just an assumption that principal is already set and is a String - unique username. Thanks to Grails convention our ConfigService is transactional so the Account domain class can use GORM dynamic finder.
OK, config fetching implementation details are out of scope here anyway. You can get, load, fetch, obtain from wherever you like to. Domain persistence, principal object, role config, external file and so on...

Any gotchas?

There is one. When running grails test command, servletContext comes as some mocked class instance without addListener method. Thus we going to have a MissingMethodException when running tests :(

Solution is typical:
def init = { servletContext ->
if (Environment.current != Environment.TEST) {
servletContext.addListener(customTimeoutSessionListener)
}
}
An unnecessary obstacle if you ask me. Should I submit a Jira issue about that?

TL;DR

Just implement a HttpSessionListener. Create a Spring bean of the listener. Inject it into BootStrap.groovy and call servletContext.addListener(injectedListener).