Drools Developer's Cookbook

Carry out the following steps in order to achieve this recipe:

The engine has the ability to automatically convert these declared facts into POJO using bytecode, creating the constructors, getter and setter methods for the fields, equals and hashcode methods, and so on. However, in order to generate them we need to know how to declare them.

The first thing that you should know is that in order to declare a fact type you have to use the declare keyword followed by the fact name, shown as follows:

declare Server

In the next line you can declare the fact fields that the fact will contain. Each field declaration is created by the field name, followed by a colon (:) and finally the field type:

<field_name> : <field_type>

Remember that if you want to use a field type that is not included in the java.lang package, you will have to import it. Also, if you want to use a previously declared fact, it should be declared before declaring the fact that will use it:

name : String
processors : int
memory : int // megabytes
diskSpace : int // gigabytes
virtualizations : List // of Virtualization objects
cpuUsage : int // percentage

After the field declarations, you have to close the fact declaration with the end keyword.

Once you have the fact declared in your rules, you have to construct a KnowledgeSession with the rule compiled. It is assumed that you already know how to do it, but there is nothing better than being sure that we are on the same page. Anyway, the following code snippet shows how to create a knowledge session:

KnowledgeBuilder kbuilder = KnowledgeBuilderFactory
    .newKnowledgeBuilder();
kbuilder.add(new ClassPathResource("rules.drl", getClass()), 
    ResourceType.DRL);
    
if (kbuilder.hasErrors()) {
    if (kbuilder.getErrors().size() > 0) {
        for (KnowledgeBuilderError kerror : kbuilder.getErrors()) {
            System.err.println(kerror);
        }
    }
}

KnowledgeBase kbase = kbuilder.newKnowledgeBase();
StatefulKnowledgeSession ksession = kbase
    .newStatefulKnowledgeSession();

After you have constructed a KnowledgeBase, you can begin to instantiate your facts in a dynamic way using the getFactType method of the KnowledgeBase object. This method needs two parameters; the first one is the package name of the rule where the fact was declared and the second one is the fact name:

FactType serverType = kbase.getFactType("drools.cookbook.chapter01", "Server");

This method returns an org.drools.definition.type.FactType object that is used to communicate with the KnowledgeBase in order to create instances of your facts. The next step is to instantiate your fact.

Object debianServer = serverType.newInstance();

This method internally uses the Java Reflection API, so you have to be aware of the exceptions. Once you have your fact instantiated it is time to fill the fields with data. To make it possible you have to use the set method of the FactType object in conjunction with three parameters. The first one is the reference of your instantiated object, the second one is the name of the field, and the last one is the field value, as you can see next.

serverType.set(debianServer, "name", "server001");

After this you are ready to insert the fact (which in this example is the debianServer object) into the StatefulKnowledgeSession.

ksession.insert(debianServer);

This is all that you have to know to declare and create your facts dynamically.

This feature is implemented using JAXB and the dependencies have to be manually added into your project if your environment doesn't provide them. If you are using Maven, the extra dependencies required are as follows:

<dependency>
  <groupId>javax.xml.bind</groupId>
  <artifactId>jaxb-api</artifactId>
  <version>2.2.1</version>
</dependency>
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-impl</artifactId>
  <version>2.2.1.1</version>
</dependency>
<dependency>
  <groupId>com.sun.xml.bind</groupId>
  <artifactId>jaxb-xjc</artifactId>
  <version>2.2.1.1</version>
</dependency>

Carry out the following steps to achieve this recipe:

In the process of adding XSD resources into a KnowledgeBase the JAXB BindingCompiler (XJC) should be notified that a XML Schema is going to be used; that is why an XJC Options object is created and configured:

com.sun.tools.xjc.Options xjcOpts = new Options();
xjcOpts.setSchemaLanguage(Language.XMLSCHEMA);

After this we have to create a JaxbConfiguration passing the previously created Options object and a system identifier as the parameters:

JaxbConfiguration jaxbConfiguration = KnowledgeBuilderFactory
    .newJaxbConfiguration(xjcOpts, "xsd");

Once we have the JaxbConfiguration object instantiated, the XSD file is ready to be added into the KnowledgeBuilder as a resource. As you should be aware, the XSD resource must be added before any rule that uses the model defined in the file; otherwise, you will get compilation errors for the rules:

kbuilder.add(new ClassPathResource("model.xsd", getClass()),    ResourceType.XSD, jaxbConfiguration);

Now, the tricky part is how to create instances of objects defined in the XSD file. Here, the reflection API is used to dynamically create and fill their fields with data. Internally, the KnowledgeBuilder compiles the XSD object's definition into Java objects, which reside in the Drools Classloader and can be accessed using the KnowledgeBase internal classloader:

CompositeClassLoader classLoader = ((InternalRuleBase) ((KnowledgeBaseImpl) kbase).getRuleBase()).getRootClassLoader();

This is an internal Drools API and could change in the future releases, which also may provide a proper public API to achieve the same results.

After following this strange way to access the Drools CompositeClassloader , you are ready to start using Java reflection to instantiate objects. In this example, first we have to get the Class definition, then obtain a new object instance, and finally start to fill its fields with values as is shown in the following code:

String className = "drools.cookbook.chapter01.Server";
Class<?> serverClass = classLoader.loadClass(className);
Object debianServer = serverClass.newInstance();
Method setName = serverClass.getMethod("setName", String.class);
setName.invoke(debianServer, "debianServer");

As you can see, the worst part of using XSD models is the use of the Reflection API to load the class definition and construct objects.

The idea of this recipe is to show how to use another alternative to model business objects, but if you want to know how to model objects using a XSD Schema, you should be aware that this goes beyond the recipe topic. Anyway, the Internet is a nice source to find some XSD tutorials. A particularly good and simple one can be found here: http://www.w3schools.com/schema/default.asp.

In this recipe, we are using SLF4J together with log4j for logging purposes. In order to use these logging frameworks, you need to add the following dependencies into your Apache Maven project:

<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>1.6.1</version>
</dependency>
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-log4j12</artifactId>
  <version>1.6.1</version>
</dependency>

Carry out the following steps in order to complete the recipe:

Internally, the Drools Framework uses an event system to expose its internal state, and that is the reason why we created and registered these event listeners. Obviously, it is not always necessary to register both listeners because this depends on the information that you want to be aware of.

As you already saw, the methods to be implemented are pretty descriptive. For example, in the activationCreated method you have access to the event created when the Activation was created. These events are ActivationEvent objects and they expose a lot of useful information; for example, you can access the KnowledgeRuntime (StatefulKnowledgeSession), and get the facts that matched the rule and caused the activation or get the name of the rule that was activated, and so on.

Once the example is executed, the event listeners will start to log every event created. Next, you will see an excerpt of a logging output with comments and information about the event:

With this information about the events, you will be able to identify what is happening inside your working memory and any possible issues. There are more events related to the engine, especially the AgendaGroup events and the ProcessEventListeners . But as a sample, these ones are enough to demonstrate how you can use them to detect the internal behavior of your rules.

Carry out the following steps to use a timer inside your rules:

When you set a cron-based timer in a rule, you are actually scheduling a sort of job that will recheck the rule patterns during a certain period of time, based on the cron date pattern.

In order to complete the cron timer's functionality, it is necessary to maintain the working memory continually checking if there are activations created to automatically fire them. To implement it you can to use the fireUntilHalt() method.

The fireUntilHalt() method will keep firing the activations created until none remains in the agenda. When no more activations are found in the agenda, it will wait until more activations appear in the active agenda group or ruleflow group.

If you have executed the previous test, maybe you expected only three alerts to be raised. However, sometimes you will see three or four alerts, because the cron job execution depends on the computer clock. This pattern specifies that the rule is going to be executed every five seconds, but not every five seconds counting from when the knowledge session is instantiated, because it takes the computer time as reference.

The cron pattern uses the standard cron syntax, which is used in UNIX-like systems to schedule jobs, and is implemented using the Quartz Framework . However, in this customized implementation seconds support was added. As a brief introduction, the cron scheduler has the following syntax where you can declare a point in time, or time intervals:

An example of a point in time is the pattern: 0 0 17 * * fri, which executes exactly at 18: 00:00 every Friday. And, if you change the last field to mon-fri we are specifying a time interval, when the job is going to be executed from Monday to Friday at 18:00:00.

In order to understand more about the cron syntax, you can use the Wikipedia page http://en.wikipedia.org/wiki/Cron as a starting point and then read the tutorials linked in its Reference section.

If you want to use this feature, you need to add another dependency in your project. Along with the minimal and required Drools dependencies (knowledge-api, drools-core, and drools-compiler), the quartz library is needed to create the calendars.

In a project managed using Apache Maven, you have to add the following XML with the dependency declaration into the POM file. Keep in mind than the minimum required quartz version is 1.6.1:

<dependency>
  <groupId>org.opensymphony.quartz</groupId>
  <artifactId>quartz</artifactId>
  <version>1.6.1</version>
</dependency>

Carry out the following steps in order to complete the recipe:

As was said in the recipe introduction, the calendar feature allows you to specify a block of time in which the rule cannot be executed. When an object is inserted into the working memory, or the working memory internal state changes because other rules are being fired, such as updating/deleting/retracting facts, it generates a new full pattern matching of the rules and the inserted facts. Once this process happens, the rules that have a calendar declaration with a false value cannot be matched, and by consequence they cannot generate new activations.

In order to configure a Drools Calendar, an org.quartz.Calendar implementation is needed. Quartz has several implementations that are ready to be used, such as a WeeklyCalendar , a HolidayCalendar , a MonthlyCalendar , and so on. It also has a customizable calendar that can be created so as to implement the org.quartz.Calendar .

For example, the WeeklyCalendar returns true by default when it is a weekday, but it can be personalized to exclude/include another day:

WeeklyCalendar calendar = new WeeklyCalendar();

Then the Drools QuartzHelper is used to create an org.drools.time.Calendar object, passed as a first parameter to the previously instantiated Quartz Calendar:

org.drools.time.Calendar onlyWeekDays = QuartzHelper.quartzCalendarAdapter(calendar);

After these steps, the calendar is ready to be registered into the StatefulKnowledgeSession object, which should be done before any object insertion. In order to register the calendar, we have to use the set(String calendarIdentifier, Calendar calendar) method of the getCalendars() KnowledgeSession method, passing the rule calendar identifier as the first parameter and the previously created org.drools.timer.Calendar as the second one.

ksession.getCalendars().set("only-weekdays", onlyWeekDays);

These are all the steps needed to register and configure the calendar. After this the StatefulKnowledgeSession is ready to be used as you normally do.

Carry out the following steps in order to achieve this recipe:

Live Queries work by opening a view and publishing events, which are pushed into the registered custom ViewChangedEventListener implementation every time the working memory's internal status changes.

In order to use the Live Queries feature it is necessary to implement a custom listener, which should implement the org.drools.runtime.rule.ViewChangedEventListener interface. This interface has three methods that should be implemented to store and update the query events. As a simple approach, a listener implementation could store the information internally in a Java Collection.

Once the ViewChangedEventListener implementation is done, it should be registered with the associated query using the openLiveQuery(String query, Object[] params, ViewChangedEventListener listener) method of the StatefulKnowledgeSession where it will be registered:

LiveQuery query = ksession.openLiveQuery("serverCpuUsage", new Object[]{20}, listener);

Here the parameters of the method are as follows:

Once the query is "opened", every time the working memory's internal state changes, the opened query results can be potentially refreshed. When the query results change, the listener is pushed with the associated information, which invokes one of the three methods implemented.

And finally, the query results are ready to be consumed based in the listener storage implementation. In this example, the server objects from the query results are stored in three different collections to know which are the current, updated, and removed servers.

Another useful feature is integration with GlazedList libraries to process the LiveQuery results. The goal of GlazedList is to let us apply transformations on List objects, such as sorting, filtering, and multiple transformations.

As a simple use in the current example, we are going to sort the output of the serverCpuUsage query based on the CPU usage.

In order to start using GlazedList, it is necessary to import the required library; it can be done using the following Apache Maven XML code snippet.

<dependency>
  <groupId>net.java.dev.glazedlists</groupId>
  <artifactId>glazedlists_java15</artifactId>
  <version>1.8.0</version>
</dependency>

Now, we have to create another custom ViewChangedEventListener implementation, but this time it also should extend the AbstractEventList class. Next, you will see an example of a listener implementation:

public class GlazedListViewChangedEventListener
                         extends AbstractEventList<Row>
                         implements ViewChangedEventListener {

    private List<Row> data = new ArrayList<Row>();

    public void rowUpdated(Row row) {
        int index = this.data.indexOf( row );   
        updates.beginEvent();
        updates.elementUpdated(index, row, row);
        updates.commitEvent();
    }

    public void rowRemoved(Row row) {
        int index = this.data.indexOf(row);
        updates.beginEvent();
        data.remove(row);
        updates.elementDeleted(index, row);       
        updates.commitEvent();
    }

    public void rowAdded(Row row) {
        int index = size();
        updates.beginEvent();
        updates.elementInserted(index, row);
        data.add(row);
        updates.commitEvent();
    }

    public void dispose() {
        data.clear();
    }

    @Override
    public Row get(int index) {
        return data.get(index);
    }

    @Override
    public int size() {
        return data.size();
    }

}

The difference with the previous listener implemented is that using GlazedList now you have to store, update, and delete the elements into the updates field provided by the AbstractEventList class.

Now, after opening the LiveQuery as we saw previously in this recipe, it is time to create the customized GlazedList object. In this example, a GlazedList SortedList object was used to order the list using the cpuUsage field as reference, as you can see in the following code snippet:

SortedList<Row> serverSortedList = new 
SortedList<Row>(listener, new Comparator<Row>() {
   public int compare(Row r1, Row r2) {
   	Server server1 = (Server) r1.get("$server");
      Server server2 = (Server) r2.get("$server");
      return (server1.getCpuUsage() – server2.getCpuUsage());
}
});

In this SortedList instance, a custom Comparator was implemented to override the default behavior, in which the objects to be compared must implement the Comparator interface. In the compare(Row r1, Row r2) method the row object is used to obtain the variable bounded in the query, in this case the $server variable name.

Once the customized GlazedList is implemented it's ready to be used to query the results, as you can see in the following code snippet:

for (Row row : serverSortedList) {
  System.out.println(row.get("$server"));
}

And lastly, don't forget to check out the examples provided with the book to complement the recipes.