Hello Readers, in this article we will take a look on how to use and implement an AgendaEventListener on a drools rule program. Before we start, check the requirements related to technologies and frameworks used to this example below:
- Maven 3.3.9
- Jboss Studio 10.3
- Drools Engine 7.0
- JDK 1.8.0_71
1. Introduction
Before continuing with the AgendaEventListener Example implementation, we need to understand how this works and which is the use of this feature inside a drools rule program.
1.1 Event Model
The drools API provides a package called org.kie.api.event. This package has all the classes that will use to add event listeners inside a rule program that will be covered on this example. The event drools’s API, provides a way to notify the user when a rule event is triggered. This includes assertion on objects values, conditions, etc.
Therefore, this API allows to separate logging and auditing tasks from your main rule program or add other functionalities, using a callback strategy.
1.2 Checking The API
In order to get more understanding on how the API works, we’ll check out the UML diagram for a rule event manager, that we will covered on this example.
The KieRuntimeManager interface is implemented by KieRuntime and provides other 2 interfaces RuleRuntimeEventManager this interface is used by the rules programs and ProcessEventManager is used by the BPM process model programs to add the listener feature that allows add more functionality to our drools programs. On this example we will cover the RuleRuntimeEventManager API.
The RuleRuntimeEventManager API expose the necessary methods to add or remove listeners, so the events related to the working memory inside a rule workflow can be listened to.
Additionally, this API expose some other methods that allows to get information about of which listeners has our rule program.
2. Setting Up The Environment
To have the dev environment setting up, please refer to my previous drools post (backward chaining) on the section 2 “Configure Necessary Tools” and uses the name drools-agenda-event-listener for the new maven drools project used on this example.
3. AgendaEventListener Example Implementation
Well, now in this section, we’ll start to implement our first agendaEventListener on a drools rule project. Below we see the steps that we’ll follow to achieve this.
- Model creation class to wrap the data that will be evaluated by the rule.
- Rule file with some example rule, in order to add a new agendaEventListener.
- Add rule configuration to the
kmodule.xmlfile, in order to get our rule on a drools session. - Test class, to put all together and see how the AgendaEventListener works.
3.1 Model Class Creation
The model class is a representation of the data that will be evaluated by the rule. On this example we will use a class called message. To create it please follow the next steps. Go to the drools-agenda-event-listener (created on the step 2) maven project on the jboss developer studio and create a new package named com.sample.model. Inside this package create a new class named Message with the below structure:
Message.java
package com.sample.model;
/**
* POJO class to wrap the example data
* that will be evaluated by the rule
*
*/
public class Message {
private int code;
private String text;
public Message(int code, String text) {
super();
this.code = code;
this.text = text;
}
public int getCode() {
return code;
}
public void setCode(int code) {
this.code = code;
}
public String getText() {
return text;
}
public void setText(String text) {
this.text = text;
}
}
3.2 Rule File Creation
The rule file will have our test rule that allows validate the data model when this is invoked and will allow to trigger our event listener. On the drools-agenda-event-listener maven project, inside the src/main/resources create a new folder named agendaeventlistenerrule. Below this folder create a new Rule file named AgendaEventListenerSample with the below structure:
AgendaEventListenerSample.drl
package com.sample
import com.sample.model.Message
/**
When this rule matched, the agenda event AfterMatchFiredEvent will be fired
*/
rule "agendatest"
when
Message( code == 20, text == "agenda example rule" )
then
System.out.println( "Rule output" );
end
This rule file must be configured on the kmodule.xml file inside src/main/resources/META-INF folder.
3.3 Add Rule Configuration
In order to get our rule program working and see how the events listeners works, it’s necessary to configure the drools session on the file kmodule.xml file inside src/main/resources/META-INF folder. See below the configuration for this example:
kmodule.xml
<?xml version="1.0" encoding="UTF-8"?>
<kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule">
<!-- drools event listener session mapping -->
<kbase name="agendaeventlistenerrule" packages="agendaeventlistenerrule">
<ksession name="ksession-agendaeventlistenerrule"/>
</kbase>
</kmodule>
3.4 Test Class Creation
Now, we are ready to add our new AgendaEventListener implementation and test it. On the drools-agenda-event-listener maven project, under the package com.sample create a new class named AgendaEventListenerTest with the below structure:
AgendaEventListenerTest.java
package com.sample;
import org.kie.api.KieServices;
import org.kie.api.event.rule.AfterMatchFiredEvent;
import org.kie.api.event.rule.DefaultAgendaEventListener;
import org.kie.api.runtime.KieContainer;
import org.kie.api.runtime.KieSession;
import com.sample.model.Message;
public class AgendaEventListenerTest {
public static void main(String[] args) {
try {
KieServices ks = KieServices.Factory.get();
KieContainer kContainer = ks.getKieClasspathContainer();
//drools session base on the xml configuration kmodule.xml
KieSession kSession = kContainer.newKieSession("ksession-agendaeventlistenerrule");
/*add the event listener in this case we'll use the DefaultAgendaEventListener,
that is a implementation of AgendaEventListener*/
kSession.addEventListener(new DefaultAgendaEventListener() {
//this event will be executed after the rule matches with the model data
public void afterMatchFired(AfterMatchFiredEvent event) {
super.afterMatchFired(event);
System.out.println(event.getMatch().getRule().getName());//prints the rule name that fires the event
}
});
//add the model with the data that will match with the rule condition
kSession.insert(new Message(20, "agenda example rule"));
//fire all the rules
kSession.fireAllRules();
} catch (Throwable t) {
t.printStackTrace();
}
}
}
The output of this program is:
Rule output // This is printing when the rule matches agendatest // This is printing by the listener after the rule matches
4. Conclusion
On this example, we learned how to make a simple implementation of listeners inside a rule workflow, how the event API is designed inside drools engine and how to use it on a drools rule program.
This drools engine feature allow us to add monitoring or logging on a rules projects, using the callback approach in order to get a clean way to add more functionality to our drools rule projects.
If you want to read more about this feature please go: AgendaEventListener
5. Download the Eclipse Project
This was a Drools AgentEventListener example with Jboss developer studio
You can download the full source code of this example here: drools-agenda-event-listener
