JBoss.orgCommunity Documentation

Drools Tools Reference Guide

Version: 3.2.1.GA


1. Introduction
1.1. What is Drools?
1.2. Drools Tools Key Features
1.3. Other relevant resources on the topic
2. Creating a New Drools Project
2.1. Creating a Sample Drools Project
2.2. Drools Project Structure Overview
2.3. Creating a New Rule
3. Debugging rules
3.1. Creating Breakpoints
3.2. Debugging
4. Editors
4.1. DSL Editor
4.1.1. Edit language mapping Wizard
4.1.2. Add language mapping Wizard
4.2. Flow Editor
4.2.1. Different types of control elements in Flow Palette
4.2.2. Different types of nodes in Flow Palette
4.3. The Rule Editor
4.3.1. Content Assist
4.3.2. Code Folding
4.3.3. Synchronization with Outline View
4.3.4. The Rete Tree View

This chapter will cover the steps required to setup an executable sample Drools project in which rules can be used.

First, we suggest that you use Drools perspective which is aimed at work with Drools specific resources.

To create a new Drools project select FileNewProject...DroolsDrools Project. This will open the New Drools Project wizard, as shown in the figure below.

On the first page type the project name and click the Next button.


Next you have the choice to add some default artifacts to it like sample rules, decision tables or ruleflows and Java classes for them. Let's select first two check boxes and click the Next button.


The next page asks you to specify a Drools runtime. If you have not yet set it up, you should do this now by clicking the Configure Workspace Settings link.


You should see the Preferences window where you can configure the workspace settings for Drools runtimes. To create a new runtime, click the Add button. The appeared dialog prompts you to enter a name for a new runtime and a path to the Drools runtime on your file system.

Note:

A Drools runtime is a collection of jars on your file system that represent one specific release of the Drools project jars. While creating a new runtime, you must either point to the release of your choice, or you can simply create a new runtime on your file system from the jars included in the Drools Eclipse plugin.


Let's simply create a new Drools 5 runtime from the jars embedded in the Drools Eclipse plugin. Thus, you should click the Create a new Drools 5 runtime button, select the folder where you want this runtime to be created and click the OK button.

You will see the newly created runtime show up in your list of Drools runtimes. Check it and click the OK button.


Now click the Finish to complete the project creation.


This will setup a basic structure, classpath, sample rules and test case to get you started.

This chapter describes how to debug rules during the execution of your Drools application.

This section will focus on how to add breakpoints in the consequences of your rules.

Whenever such a breakpoint is encountered during the execution of the rules, the execution is halted. Once the execution is halted, it's possible to inspect the variables known at that point and use any of the default debugging actions to decide what should happen next (step over, continue, etc). To inspect the content of the working memory and agenda the Debug views can be used.

To create breakpoints in the Package Explorer view or Navigator view of the Drools perspective, double-click the selected .drl file to open it in the editor. In the example below we opened Sample.drl file.

You can add and remove rule breakpoints in the .drl files in two ways, similar to the way breakpoints are added to Java files:


The Debug perspective contains a Breakpoints view which can be used to see all defined breakpoints, get their properties, enable/disable or remove them, etc. You can switch to it by navigating to WindowPerspectiveOthersDebug.

Drools breakpoints are only enabled if you debug your application as a Drools Application. To do this you should perform one of the actions:


  • Alternatively, you can also select Debug AsDebug Configuration to open a new dialog for creating, managing and running debug configurations.

    Select the Drools Application item in the left tree and click the New launch configuration button (leftmost icon in the toolbar above the tree). This will create a new configuration with a number of the properties already filled in (like the Project and Main class) based on main class you selected in the beginning. All properties shown here are the same as any standard Java program.


Tip:

Remember to change the name of your debug configuration to something meaningful.

Next click the Debug button on the bottom to start debugging your application.

After enabling the debugging, the application starts executing and will halt if any breakpoint is encountered. This can be a Drools rule breakpoint, or any other standard Java breakpoint. Whenever a Drools rule breakpoint is encountered, the corresponding .drl file is opened and the active line is highlighted. The Variables view also contains all rule parameters and their value. You can then use the default Java debug actions to decide what to do next (resume, terminate, step over, etc). The debug views can also be used to determine the contents of the working memory and agenda at that time as well (you don't have to select a working memory now, the current executing working memory is automatically shown).

A domain-specific language is a set of custom rules, that is created specifically to solve problems in a particular domain and is not intended to be able to solve problems outside it. A DSL's configuration is stored in plain text.

In Drools this configuration is presented by .dsl files that can be created selecting FileNewOtherDroolsDomain Specific Language from the projects context menu.

DSL Editor is a default editor for .dsl files:


In the table below all the components of the DSL Editor page are described:

Table 4.1. DSL Editor Components.

ComponentsDescription
DescriptionUser's comments on a certain language message mapping
Table of language message mappingsThe table is divided into 4 rows: By clicking on some row's header you can sort the lines in the table according to the clicked row. By double clicking on the line the Section 4.1.1, “Edit language mapping Wizard” will be open.
ExpressionShows the language expression of the selected table line (language message mapping).
MappingShows the rule of language mapping for the selected table line (language message mapping).
ObjectShows the object for the selected table line (language message mapping)
Sort By Using this option you can change the sorting order of the language message mappings. To do this select from the drop down list the method of sorting you want and click the Sort button.
Buttons
  • Edit: by clicking the button users can edit the selected line in the language message mappings table. For more information look at the Section 4.1.1, “Edit language mapping Wizard” section.

  • Remove: if you click the button the selected mapping line will be deleted.

  • Add: with this button you can add new mapping lines to the table. For more information look at the Section 4.1.2, “Add language mapping Wizard” section.

  • Sort: please, for more information see the Sort By row above.

  • Copy: with this button you can add new mapping lines to the table in which all the information will be copied from the selected mapping line.


This wizard is equal to the wizard described in Section 4.1.1, “Edit language mapping Wizard”. It can be opened by clicking the Add button.

The only difference is that instead of editing the information you should enter new one.


Drools tools also provides the ability to define the order in which rules should be executed. The Ruleflow file allows you to specify the order in which rule sets should be evaluated using a flow chart. This allows you to define which rule sets should be evaluated in sequence or in parallel as well as specify the conditions under which rule sets should be evaluated.

Ruleflows can be set only by using the graphical flow editor which is part of the Drools plugin for Eclipse. Once you have set up a Drools project,you can start adding ruleflows. Add a ruleflow file(.rf) by clicking on the project and selecting FileNewOther...Flow File:


By default these ruleflow files (.rf) are opened in the graphical Flow editor. You can see this in the picture below.


The Flow editor consists of a palette, a canvas and an outline view. To add new elements to the canvas, select the element you would like to create in the palette and then add it to the canvas by clicking on the preferred location.


Clicking on the Select option in the palette and then on the element in your ruleflow allows you to view and set the properties of that element in the Properties view.


The Outline view is useful for big complex schemata where not all nodes are seen at one time. So using your Outline view you can easily navigate between parts of a schema.


Currently, ruleflow supports seven types of nodes. In the table below you can find information about them:

Table 4.3. Flow Palette Components.Part 2.

Component PictureComponent NameDescription
Start Event The start of the ruleflow. A ruleflow should have exactly one start node. The Start Event can not have incoming connections and should have one outgoing connection. Whenever the ruleflow process is started, the execution is started here and is automatically proceeded to the first node linked to this Start Event
End Event A ruleflow file can have one or more End Events. The End Event node should have one incoming connection and can not have outgoing connections. When an end node is reached in the ruleflow, the ruleflow is terminated (including other remaining active nodes when parallelism is used).
Rule Task Represents a set of rules. A Rule Task node should have one incoming connection and one outgoing connection. The RuleFlowGroup property which is used to specify the name of the ruleflow-group that represents the set of rules of this Rule Task node. When a Rule Task node is reached in the ruleflow, the engine will start executing rules that are a part of the corresponding ruleflow-group. Execution automatically continues to the next node when there are no more active rules in this ruleflow-group.
Gateway[diverge] Allows you to create branches in your ruleflow. A Gateway[diverge] node should have one incoming connection and two or more outgoing connections.
Gateway[converge] Allows you to synchronize multiple branches. A Gateway[converge] node should have two or more incoming connections and one outgoing connection.
Reusable Sup-Process Represents the invocation of another ruleflow from this ruleflow. A subflow node should have one incoming connection and one outgoing connection. It contains the property processId which specifies the id of the process that should be executed. When a Reusable Sup-Process node is reached in the ruleflow, the engine will start the process with the given id. The subflow node will only continue if that subflow process has terminated its execution. Note that the subflow process is started as an independent process, which means that the subflow process will not be terminated if this process reaches an end node.
Script Task Represents an action that should be executed in this ruleflow. An Script Task node should have one incoming connection and one outgoing connection. It contains the property "action" which specifies the action that should be executed. When a Script Task node is reached in the ruleflow, it will execute the action and continue with the next node. An action should be specified as a piece of (valid) MVEL code.

The Rule editor works on files that have a .drl (or .rule in the case of spreading rules across multiple rule files) extension.


The editor follows the pattern of a normal text editor in eclipse, with all the normal features of a text editor: