Usage

Prerequisites

  • Use Maven 3.0.x (x >= 3)
  • Starting with version 0.3.1, the plugin is available from Maven Central. No configuration of additional remote repositories necessary.

Usage Example

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>example-knowledge-module</artifactId>
  <version>1.0.0</version>
  <packaging>knowledge-module</packaging>    <!-- notice the new packaging type -->

  <name>An example Drools Knowledge Module</name>

  <build>
    <plugins>
      <plugin>
        <groupId>de.lightful.maven.plugins</groupId>
        <artifactId>maven-drools-plugin</artifactId>
        <version>0.3.1</version>
        <!-- vv== set extensions flag to true: this makes packaging type available to build -->
        <extensions>true</extensions>
        <!-- Depending on Drools runtime desired, define correct version of these dependencies: -->
        <dependencies>
          <dependency>
            <groupId>org.drools</groupId>
            <artifactId>knowledge-api</artifactId>
            <version>[5.3.0.Final]</version>
          </dependency>
          <dependency>
            <groupId>org.drools</groupId>
            <artifactId>drools-core</artifactId>
            <version>[5.3.0.Final]</version>
          </dependency>
          <dependency>
            <groupId>org.drools</groupId>
            <artifactId>drools-compiler</artifactId>
            <version>[5.3.0.Final]</version>
          </dependency>
        </dependencies>
        <configuration>
          <passes>
            <pass>
              <name>First Pass</name>
              <ruleSourceRoot>${basedir}/src/main/rules/pass-one</ruleSourceRoot>
              <includes>
                <include>**/*.drl</include>
              </includes>
              <excludes>
                <exclude>**/Test*.drl</exclude>
              </excludes>
            </pass>
          </passes>
        </configuration>
      </plugin>
    </plugins>
  </build>

  <dependencies>
    <!-- these are (actually existing) example dependencies -->
    <!-- used for testing the plugin:                       -->
    <!--
         Not yet available from Maven Central. If you'd like
         to use them, configure 

           http://lightful.de/mvnrepo/public/releases

         as an additional Maven remote repository.
    -->
    <dependency>
      <groupId>de.lightful.maven.drools.plugin.itartifacts</groupId>
      <artifactId>drools-fruit-types-5.3.0.Final</artifactId>
      <version>0.1.2</version>
      <type>dkm</type> <!-- use dkm as type specifier in dependencies -->
    </dependency>
    <dependency>
      <groupId>de.lightful.maven.drools.plugin.itartifacts</groupId>
      <artifactId>cities-fact-model</artifactId>
      <version>0.0.18</version>
    </dependency>
  </dependencies>

</project>

A few things to notice

  • specify the packaging type as knowledge-module
  • you can list as many <pass>es as you want. The passes are executed sequentially in declaration order.
    Multiple passes caters to the use-case of using Drools' declare keyword to create user-defined types which are then used in other source files. Since the regular KnowledgeBuilder does not support forward references, one has to sort out dependencies manually. Introducing multiple compiler passes with different sets of files to compile helps to alleviate this problem.
  • each <pass> can have one <name> which is just a name echoed on the console during compilation. If you don't specify one, a default name will be generated.
  • each <pass> can contain a <ruleSourceRoot> specifying where all the rules for this pass must live.
  • each <pass> can contain <includes> and <excludes>, which should be known from various other plugins. If you don't specify any includes, a default include **/*.drl will be used. The default excludes set is empty.
  • You must not include the Drools runtime libraries (like drools-compiler, drools-core etc.) into the <dependencies> section of the knowledge module. The runtime libraries have to be defined as dependencies of the plugin, like shown in the example. If you forget about this, you will get nasty class cast exceptions: the runtime libraries will be loaded twice, each by different class loaders. For details, see this FAQ entry.
  • Supported Drools runtime versions: 5.3.0.Final, 5.4.0.Final. Support for older Drools versions was dropped with plugin version 0.3.1 due to breaking API changes in Drools.

Example output

Call mvn clean verify on the example project above with a few rules in src/main/rules/pass-one and you will get something like:

[INFO] --- maven-drools-plugin:0.2.4:compile (default-compile) @ example-knowledge-module ---
... maven download logging skipped for brevity ...
[INFO] This is the compiler plugin
[INFO] Passes: [Pass{name='First Pass', ruleSourceRoot=/home/someuser/example-knowledge-module/src/main/rules/pass-one, includes=[**/*.drl], excludes=[**/Test*.drl]}]
[INFO] Project: An example Drools Knowledge Module
[INFO] Pass #1:
[INFO]     Name:             'First Pass'
[INFO]     Rule Source Root: /home/someuser/example-knowledge-module/src/main/rules/pass-one
[INFO]     Includes:         ['**/*.drl']
[INFO]     Excludes:         ['**/Test*.drl']
[INFO] Using Drools Runtime version 5.3.0.Final
[INFO] Resolved dependencies of com.example:example-knowledge-module:dkm:1.0.0 (compile).
[INFO] 

Using class loader with these URLs:
[INFO] URL in use (#1): file:/home/someuser/.m2/repository/de/lightful/maven/drools/plugin/itartifacts/cities-fact-model/0.0.18/cities-fact-model-0.0.18.jar
[INFO] Loaded drools dependency de.lightful.maven.drools.plugin.itartifacts:drools-fruit-types-5.3.0.Final:dkm:0.1.2
[INFO]   Contains packages:
[INFO]     model.fruit
[INFO]       type 'WeightOfFruit': 
[INFO]         field 'fruit' is of type model.fruit.Fruit
[INFO]         field 'weight' is of type java.lang.Integer
[INFO]       type 'Fruit': 
[INFO]         field 'name' is of type java.lang.String
[INFO] Executing compiler pass 'First Pass'...
[INFO]   Compiling rule file '/home/someuser/example-knowledge-module/src/main/rules/pass-one/cool-rule.drl' ...
[INFO] Done with compiler pass 'First Pass'.
[INFO] Writing 1 knowledge packages into output file /home/someuser/example-knowledge-module/target/example-knowledge-module-1.0.0.dkm
[INFO]   Package #1: com.example.pricing (1 rules)
[INFO] Setting project artifact to /home/someuser/example-knowledge-module/target/example-knowledge-module-1.0.0.dkm
[INFO] 
[INFO] --- maven-compiler-plugin:2.3.2:testCompile (default-testCompile) @ example-knowledge-module ---
[WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent!
[INFO] Compiling 1 source file to /home/someuser/example-knowledge-module/target/test-classes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 5.452s
[INFO] Finished at: Mon Nov 28 22:43:39 CET 2011
[INFO] Final Memory: 21M/490M
[INFO] ------------------------------------------------------------------------