Chapter 9. Using Red Hat JBoss Developer Studio to Create and Test Rules

There are many ways to author rules in BRMS, however as a developer you would prefer an Integrated Development Environment (IDE) such as Red Hat JBoss Developer Studio that offers you advanced tooling and content assistance. Red Hat JBoss BRMS and Red Hat JBoss BPM Suite tooling are compatible with Red Hat JBoss Developer Studio version 7 and above. The Red Hat JBoss Developer Studio with Red Hat JBoss BPM Suite/BRMS plug-ins simplify your development tasks. These plug-ins provide the following features:

  • Simple wizards for rule and project creation.
  • Content assistance for generating the basic rule structure. For example, If you open a .drl file in the Red Hat JBoss Developer Studio editor and type ru, and press Ctrl+Space , the template rule structure is created.
  • Syntax coloring.
  • Error highlighting.
  • IntelliSense code completion.
  • Outline view to display an outline of your structured rule project.
  • Debug perspective for rules and process debugging.
  • Rete tree view to display Rete network.
  • Editor for modifying business process diagram.
  • Support for unit testing using JUnit and TestNG.

9.1. Red Hat JBoss Developer Studio Drools Perspective

Red Hat JBoss Developer Studio comes with all the BRMS and BPM Suite plug-in requirements pre-packaged with it. It offers the following perspectives:

  • Drools: allows you to work with Red Hat JBoss BRMS specific resources.
  • Business Central Repository Exploring.
  • jBPM: allows you to work with Red Hat JBoss BPM Suite resources.

9.2. Red Hat JBoss BRMS Runtimes

A Drools runtime is a collection of JAR files 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 create a new runtime on your file system from the jars included in the Drools plug-in. For creating a new runtime, you need to specify a default Drools runtime for your Eclipse workspace, but each individual project can override the default and select the appropriate runtime for that project specifically. You can add as many Drools runtimes as you need. In order to use the Red Hat JBoss BRMS plug-in with Red Hat JBoss Developer Studio, it is necessary to set up the runtime.

9.2.1. Defining a Red Hat JBoss BRMS Runtime

  1. Extract the runtime JAR files located in the jboss-brms-engine.zip archive of the Red Hat JBoss BRMS 6.4.0 Core Engine ZIP archive available on the Red Hat Customer Portal.
  2. From the Red Hat JBoss Developer Studio menu, click WindowPreferences.
  3. Select DroolsInstalled Drools Runtimes.
  4. Click Add…​, provide a name for the new runtime, and click Browse to navigate to the directory where you extracted the runtime files in the first step. Click OK to register the selected runtime in Red Hat JBoss Developer Studio.
  5. Mark the runtime you have created as the default Drools runtime by clicking on the check box next to it.
  6. Click OK. If you already have projects in Red Hat JBoss Developer Studio, a dialog box will indicate that you have to restart Red Hat JBoss Developer Studio to update the runtime.

9.2.2. Selecting a Runtime for Your Red Hat JBoss BRMS Project

Whenever you create a Drools project either by using the New Drools Project wizard or by converting an existing Java project to a Drools project, the Drools plug-in automatically adds all the required JAR files to the classpath of your project.

If you are creating a new Drools project, the plug-in uses the default Drools runtime for that project, unless you specify a project-specific one.

To define a project-specific runtime, create a new Drools project and choose the desired runtime in the final step of the New Drools Project wizard. Alternatively, you can create a new runtime by clicking Manage Runtime Definitions.

9.2.3. Changing the Runtime of Your Red Hat JBoss BRMS Project

To change the runtime of a Drools project:

  1. In the Drools perspective, right-click the project and select Properties.

    The project properties dialog opens.

  2. Navigate and select the Drools category.
  3. Check the Enable project specific settings checkbox and select the appropriate runtime from the drop-down box.

    If you click the Configure workspace settings…​ link, the workspace preferences showing the currently installed Drools runtimes opens. You can add new runtimes there if required. If you uncheck the Enable project specific settings checkbox, it uses the default runtime as defined in your global preferences.

  4. Click OK.

9.2.4. Configuring the Red Hat JBoss BRMS Server

Red Hat JBoss Developer Studio can be configured to run the Red Hat JBoss BRMS\BPM Suite Server.

Configuring the Server

  1. Open the Drools view by clicking WindowOpen PerspectiveOther and then Drools. Click OK.
  2. Add the Server view by clicking WindowShow ViewOther…​ and then ServerServers.
  3. Open the server menu by right clicking the Servers panel. Click NewServer to add a new server.
  4. Define the server by selecting JBoss Enterprise MiddlewareJBoss Enterprise Application Platform 6.1+, and click Next.
  5. Click JBoss EAP 6.4 Runtime and select Create new runtime (next page). Click Next.
  6. Set the home directory by clicking Browse. Navigate to and select the installation directory for Red Hat JBoss EAP 6.4 that has Red Hat JBoss BPM Suite installed.
  7. Provide a name for the server in the Name field, make sure that the configuration file is set, and click Finish.

9.3. Exploring Red Hat JBoss BRMS Application

A BRMS project typically comprises the following:

  • Facts, which are a set of java class files, often POJOs.
  • Rules, which operate on the facts.
  • Drools library (JAR files) for executing the rules.

Red Hat JBoss Developer Studio helps you generate the getter and setter methods for attributes automatically. When you create a BRMS or a BPM Suite project, the following directories are generated:

  • src/main/java that stores the class files (facts).
  • src/main/resources/rules that stores the .drl files (rules).
  • src/main/resources/process that stores the .bpmn files (processes).

9.4. Creating a Red Hat JBoss BRMS Project

To create a new Red Hat JBoss BRMS project in the Drools perspective, do the following:

Procedure: Creating New Red Hat JBoss Developer Studio Project

  1. In the main menu, click FileNewProject.
  2. Click DroolsDrools Project and click Next.
  3. For now, choose the second option. Red Hat JBoss Developer Studio will create a project with a Red Hat JBoss BPM Suite example. Click Next.
  4. Enter a name for the project into the Project name: text box and click Finish.

To test the project:

  1. Navigate to the src/main/java directory and expand the com.sample package.
  2. Right click the desired Java class and click Run AsJava Application.

    The output will be displayed on the console tab.

If you checked the default artifacts checkboxes in the Drools Project wizard, you can see the newly created Drools project in the Package Explorer accordingly containing:

  • A sample rule Sample.drl in the src/main/resources/rules directory.
  • A sample process Sample.bpmn in the src/main/resources/process directory.
  • A sample decision table Sample.xls in the src/main/resources/dtables directory.
  • An example DroolsTest.java Java class in the src/main/java directory to execute the rules in the Drools engine in the com.sample package.
  • An example ProcessTest.java Java class in the src/main/java directory to execute the rules in the Drools engine in the com.sample package.
  • An example DecisionTableTest.java Java class in the src/main/java directory to execute the rules in the Drools engine in the com.sample package.

9.5. Using Textual Rule Editor

In the Package Explorer, you can double-click your existing rule file to open it on a textual rule editor or choose FileNewRule Resource to create a new rule on the textual editor. The textual rule editor has a pattern of a normal text editor and this is where you modify and manage your rules.

The textual rule editor works on files that have a .drl (or .rule) extension. Usually these contain related rules, but it is also possible to have rules in individual files, grouped by being in the same package namespace. These DRL files are plain text files. Even if your rule group is using a domain specific language (DSL), the rules are still stored as plain text. This allows easy management of rules and versions.

Textual editor provides features like:

  • Content assistance: The pop-up content assistance helps you quickly create rule attributes such as functions, import statements, and package declarations. You can invoke pop-up content assistance by pressing Ctrl+Space.
  • Code folding: Code Folding allows you to hide and show sections of a file use the icons with minus and plus on the left vertical line of the editor.
  • Sysnchronization with outline view: The text editor is in sync with the structure of the rules in the outline view as soon as you save your rules. The outline view provides a quick way of navigating around rules by name, or even in a file containing hundreds of rules. The items are sorted alphabetically by default.

9.6. Red Hat JBoss BRMS Views

You can alternate between these views when modifying rules:

Working Memory View
Shows all elements in the Red Hat JBoss BRMS working memory.
Agenda View
Shows all elements on the agenda. For each rule on the agenda, the rule name and bound variables are shown.
Global Data View
Shows all global data currently defined in the Red Hat JBoss BRMS working memory.
Audit View
Can be used to display audit logs containing events that were logged during the execution of a rules engine, in tree form.
Rete View

This shows you the current Rete Network for your DRL file. You display it by clicking on the tab "Rete Tree" at the bottom of the DRL Editor window. With the Rete Network visualization being open, you can use drag-and-drop on individual nodes to arrange optimal network overview. You may also select multiple nodes by dragging a rectangle over them so the entire group can be moved around.

Note

The Rete view works only in projects where the rule builder is set in the project´s properties. For other projects, you can use a workaround. Set up a Red Hat JBoss BRMS project next to your current project and transfer the libraries and the DRLs you want to inspect with the Rete view. Click on the right tab below in the DRL Editor, then click Generate Rete View.

Kie Navigator View
Shows you the contents of your Red Hat JBoss BPM Suite projects on your container. See chapter Kie Navigator of the Red Hat JBoss BPM Suite Getting Started Guide for more information.

9.7. Debugging Rules

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

  • Select the main class of your application. Right-click on it and select Debug AsDrools Application.
  • Alternatively, select Debug AsDebug Configuration to open a new dialog window for creating, managing and running debug configurations.

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

    Note

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

    1. Click the Debug button on the bottom to start debugging your application.
    2. 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, and others). The debug views can also be used to determine the contents of the working memory and agenda at that time as well (the current executing working memory is automatically shown).

9.7.1. Creating Breakpoints

Create breakpoints to help monitor rules that have been executed. Instead of waiting for the result to appear at the end of the process, you can inspect the details of the execution at each breakpoint you set. This is useful for debugging and ensuring rules are executed as expected.

  1. To create breakpoints in the Package Explorer view or Navigator view of the Red Hat JBoss BRMS perspective, double-click the selected .drl file to open it in the editor.
  2. You can add and remove rule breakpoints in the .drl files in two ways:

    • Double-click the rule in the Rule editor at the line where you want to add a breakpoint. A breakpoint can be removed by double-clicking the rule once more.

      Note

      Rule breakpoints can only be created in the consequence of a rule. Double-clicking on a line where no breakpoint is allowed does nothing.

    • Right-click the ruler. Select the Toggle Breakpoint action in the context menu. Choosing this action adds a breakpoint at the selected line or remove it if there is one already.
  3. The Debug perspective contains a Breakpoints view which can be used to see all defined breakpoints, get their properties, enable/disable and remove them. You can switch to it by clicking WindowPerspectiveOthersDebug.