As mentioned before Drools 4.0 is a major update over the previous Drools 3.0.x series. Unfortunately, in order to achieve the goals set for this release, some backward compatibility issues were introduced, as discussed in the mail list and blogs.
This section of the manual is a work in progress and will document a simple how-to on upgrading from Drools 3.0.x to Drools 4.0.x.
There are a few API changes that are visible to regular users and need to be fixed.
Drools 3.0.x had only one working memory type that worked like a stateful working memory. Drools 4.0.x introduces separate APIs for Stateful and Stateless working memories that are called now Rule Sessions. In Drools 3.0.x, the code to create a working memory was:
In Drools 4.0.x it must be changed to:
Example 1.2. Drools 4.0.x: Stateful Rule Session Creation
StatefulSession wm = rulebase.newStatefulSession();
The StatefulSession object has the same behavior as the
Drools 3.0.x WorkingMemory (it even extends the WorkingMemory
interface), so there should be no other problems with this fix.
Drools 4.0.x now supports pluggable dialects and has built-in support for Java and MVEL scripting language. In order to avoid keyword conflicts, the working memory actions were renamed as showed bellow:
Table 1.1. Working Memory Actions equivalent API methods
| Drools 3.0.x | Drools 4.0.x |
| WorkingMemory.assertObject() | WorkingMemory.insert() |
| WorkingMemory.assertLogicalObject() | WorkingMemory.insertLogical() |
| WorkingMemory.modifyObject() | WorkingMemory.update() |
The DRL Rule Language also has some backward incompatible changes as detailed bellow.
The Working Memory actions in rule consequences were also changed in a similar way to the change made in the API. The following table summarizes the change:
Table 1.2. Working Memory Actions equivalent DRL commands
| Drools 3.0.x | Drools 4.0.x |
| assert() | insert() |
| assertLogical() | insertLogical() |
| modify() | update() |
Drools 3.0.x did not had native support for primitive types and consequently, it auto-boxed all primitives in it's respective wrapper classes. That way, any use of a boxed variable binding required a manual unbox.
Drools 4.0.x has full support for primitive types and does not wrap values anymore. So, all previous unwrap method calls must be removed from the DRL.
Example 1.3. Drools 3.0.x manual unwrap
rule "Primitive int manual unbox"
when
$c : Cheese( $price : price )
then
$c.setPrice( $price.intValue() * 2 )
end
The above rule in 4.0.x would be:
Example 1.4. Drools 4.0.x primitive support
rule "Primitive support"
when
$c : Cheese( $price : price )
then
$c.setPrice( $price * 2 )
end
The Drools Update tools is a simple program to help with the upgrade of DRL files from Drools 3.0.x to Drools 4.0.x.
At this point, its main objective is to upgrade the memory action calls from 3.0.x to 4.0.x, but expect it to grow over the next few weeks covering additional scenarios. It is important to note that it does not make a dumb text search and replace in rules file, but it actually parses the rules file and try to make sure it is not doing anything unexpected, and as so, it is a safe tool to use for upgrade large sets of rule files.
The drools update tool can be found as a maven project in the following source repository http://anonsvn.labs.jboss.com/labs/jbossrules/trunk/experimental/drools-update/ you just need to check it out, and execute the maven clean install action with the project's pom.xml file. After resolve all the class path dependencies you are able to run the toll with the following command:
java -cp $CLASSPATH org.drools.tools.update.UpdateTool -f <filemask> [-d <basedir>] [-s <sufix>]
The program parameters are very easy to understand as following.
-h,--help, Shows a very simple list the usage help
-d your source base directory
-f pattern for the files to be updated. The format is the same as used by ANT: * = single file, directory ** = any level of subdirectories EXAMPLE: src/main/resources/**/*.drl = matches all DRL files inside any subdirectory of /src/main/resources
-s,--sufix the sufix to be added to all updated files
It is important to note that the DSL template engine was rewritten from scratch to improve flexibility. One of the new features of DSL grammars is the support to Regular Expressions. This way, now you can write your mappings using regexp to have additional flexibility, as explained in the DSL chapter. Although, now you have to escape characters with regexp meaning. Example: if previously you had a matching like:
Now, you need to escape '[' and ']' characters, as they have special meaning in regexps. So, the same mapping in Drools 4.0 would be:
Example 1.6. Drools 4.0.x mapping with escaped characters
[when][]- the {attr} is in \[ {values} \]={attr} in ( {values} )