The Dictionary file (or DSL) is a text file (with a .dsl extension) that contains DSL entries. Each line of this file starting with an opening bracket "[" is considered a DSL entry. Lines starting with hash character # are considered comments. Lines starting with something other than an opening bracket or a hash symbol are considered to be part of the previous DSL entry. The format of a DSL entry is as follows:

[<scope>][<type definition>]<dsl expression>=<replacement text>

The <scope> section currently supports four different types:

The <type definition> section is not mandatory (we can either omit it or use empty brackets []) and it is used as a hint for editors such as KIE-Workbench.

After the <type definition> comes the <dsl expression>. This is the text that will be matched and replaced in the DSLR file. A <dsl expression> consists of a Java regular expression (https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html) and any number of embedded variable definitions. A variable definition is enclosed in braces ("{" and "}") and it consists in a variable name and two optional sections separated by a colon ":". If only one optional section is present, it is used as a regular expression to match text that will be assigned to the variable; if the two optional sections are present, the first one is used as a hint for an editor (such as the KIE-Workbench) and the second one is the regular expression. A <dsl expression> always ends with an equal sign (=).

What follows after the equals sign is the <replacement text> that will be used to replace any part of the DSLR file matching the <dsl expression>. Variables defined in the <dsl expression> section can be used in this section, just like named regular expression matching groups, by using the name of the variable enclosed in braces. Optionally, the variable name may be followed by an exclamation point "!" and a transformation function. The supported transformation functions are detailed in the following table.

A typical (and very simplistic) DSL entry might look like the following:

[when]There is a Customer=Customer()

The previous entry is defining a DSL entry that will replace any occurrence of the text There is a Customer inside a DSLR file with the corresponding DRL Customer().

[when]There is a Customer=Customer()
[when]- age greater than {years:d*} years=age > {years}
[when]- category is {category:w*}=category == Customer.Category.{category}

rule "A GOLD Customer older than 31 years"
when
    There is a Customer- age greater than 31 years
        - category is GOLD
then
    ...
end

rule "A GOLD Customer older than 31 years"
when
    Customer(age > 31, category == Customer.Category.GOLD)
then
    ...
end

[when]There is a Customer=$c: Customer()
[when]- age greater than {years:d*} years=age > {years}
[then]Update Customer=modify($c){}
[then]- set Category to {category:w*}= setCategory(Customer.Category.{category})

rule "Mark Customers older than 31 years as BRONZE"
when
    There is a Customer- age greater than 31 years
then
    Update Customer
        - set Category to BRONZE
end

rule "Mark Customers older than 31 years as BRONZE"
when
    $c: Customer(age > 31)
then
    modify ($c) { setCategory(Customer.Category.BRONZE) }
end

A rules file, also referred to as a DSLR file, is a text file with a .dslr extension. DSLR files define Drools rules using a domain-specific language. Previous versions of Drools required the DSLR file to specify which DSL had to be used to process it. This is no longer the case in the current version of Drools; all DSL files included in a KIE Base are going to be used to process any DSLR file also found in that same KIE Base.

The translation of a DSLR file into DRL follows these steps:

A detailed explanation of the translation process can be found in Drools' documentation: http://docs.jboss.org/drools/release/6.3.0.Final/drools-docs/html/ch08.html#d0e11300.

By default, plain DRL or Java syntax is not allowed in a DSLR file. However, there is a mechanism to mix DRL and Java sentences along with DSL inside a DSLR file for experienced users. Any line in a DSLR resource starting with a greater than sign > will be skipped by the translator and will remain unmodified in the final DRL resource. This facility provides the means to overcome some limitations of DSL.

One of the most difficult aspects of working with DSL/DSLR is understanding and fixing errors. The fundamental issue is that errors are reported based on the generated DRL, and will not refer to the high-level DSLR statements used to create the DRL.

There are some methods we can use though to make the detection and correction of errors easier.

The first handy feature we have resides in the DSL itself. Using a special type of comment starting with # we can make Drools log certain information regarding the DSL translation process. This special comment could contain the following keywords that will enable specific features of the DSL debug capabilities:

As an example, we could add the following line to one of the DSL examples in the source bundle:

#/ debug display result, steps and  usage

By adding this line, Drools will log some statistics regarding the usage of each DSL sentence (usage), the conversion steps involved in each DSLR sentence (steps), and the final DRL (result).

There is another way we can use to generate DRL from DSL/DSLR for debugging purposes, and it involves the internal classes that Drools' compiler uses for this task: org.drools.compiler.compiler.DrlParser, and org.drools.compiler.lang.dsl.DefaultExpanderResolver. Using a combination of these two classes we can convert DSL and DSLR resources into DRL to analyze what the final result looks like. The following lines will convert some DSL and DSLR resources into plain DRL:

String dslContent = //Get the DSL content from somewhere
String dslrContent = //Get the DSLR content from somewhere
DrlParser parser = new DrlParser();
DefaultExpanderResolver resolver = new DefaultExpanderResolver(new StringReader(dslContent));
String drl = parser.getExpandedDRL( dslrContent, resolver);

After this code gets executed, the drl String will contain the expanded DRL code.

Let's now move to a concrete scenario showing all the topics introduced so far.

Let's now put it all together in a simple example. Going back to our e-shop, let's assume we want to create some classification rules for our Customers. In this simple example, the classification logic will be based on the age of the Customer. Because we want SMEs to write the rules, we have to provide them with a simple, domain-specific language containing only those expressions that apply to this scenario. The SME will then use this tailored language to express the necessary business logic. Let's assume that the business logic we want to implement is the following:

The categorization rules must only be applied if the customer doesn't have a category already assigned (meaning that the current category is N/A).

A proposed DSL for the described scenario is shown next:

# Simple DSL example file
[keyword]avoid looping=no-loop true
[when]There is a Customer=$c:Customer()
[when]- with age between {low:d*} and {high:d*}=age >= {low}, age <= {high}
[when]- who is older than {low:d*}=age > {low}
[when]- without a Category set=category == Customer.Category.NA
[then]Set Customer Category to {category:w*}=modify($c){ setCategory(Customer.Category.{category}) };

The first sentence after the initial comment is a [keyword] that will allow us to use a more user-friendly alternative for the no-loop attribute in our rules. Following the [keyword] we find four [when] sentences. These sentences will allow us to write the necessary rules for the scenario we are dealing with. The last sentence is a [then]. This sentence can be used to set a category to the customer. The braces belonging to the modify statement have to be escaped ({ and }) so they don't conflict with a variable reference.

The following DSLR rule is only one of the four required rules the SME needs to write. A complete implementation and unit test of this scenario can be found in the source bundle associated with this chapter:

rule "Categorize Customers between 22 and 30"
avoid looping
when
    There is a Customer
        - with age between 22 and 30
        - without a Category set
then
    Set Customer Category to BRONZE
end

After the previous rule gets translated into DRL, the result will look like the following:

rule "Categorize Customers between 22 and 30"
no-loop true
when
    $c: Customer( age >= 22, age <= 30, category == Customer.Category.NA)
then
    modify($c){ setCategory(Customer.Category.BRONZE) }
end

We can clearly identify which of the previous 2 rules is more business-oriented.

One of the limitations of DSL is that SMEs still need to know what the available sentences are and how they can interact with each other. They still need to manually write the rules in a text editor. But one of the advantages of DSL is that, by having a limited set of sentences, it is easy to build a tailored UI for the SMEs to use. Both the Drools Eclipse plugin and KIE-Workbench have support for DSL and DSLR creation and usage. These two applications are, unfortunately, beyond the scope of this book.

As mentioned before, the source bundle included with this chapter contains a complete implementation of the previously described scenario as well as a more elaborated scenario, where the categorization of the Customers is based on the number of Orders they have.

Categorization rules allow us to introduce the next topic in this chapter.