Skip to: Site menu | Main content

Drools

Java Rules Engine

Drools.NET Installation and User Guide Print

           

   

User Guide for Drools.NET

V1.0-Jan 29, 2006

  

                                                                                                  

  About this Document

This document is the installation and user guide for Drools.NET

REVISION HISTORY

Date

Description

1.        Jan 29, 2006

Created

2.        Apr 06, 2006  Updated to include .NET Framework v1.1 support documentation
3.         



 

Table of Contents

 1   EXECUTIVE SUMMARY  

1.1     Purpose

1.2     Business Vision

2   Drools.NET Installation

2.1     System Requirements

2.2     Release Contents

2.3     Installation

3   Drools.NET Features Description and Usage

3.1     Using Basic Features of Drools

3.1.1         RuleBaseLoader

3.1.2         RuleBaseBuilder

3.2     Drools.NET Decision Tables

3.2.1         Getting Drools.NET Decision Tables working

3.2.2         Drools.NET v/s Drools Decision Tables

3.2.3         Syntax of Decision Tables

3.3     Pre-Compilation Support

3.4     Support for Multiple .NET languages

3.5     Support for .NET Framwork 1.1 and 2.0

4   Running Examples 11



 

 

1          EXECUTIVE SUMMARY 

 

1.1       Purpose

This document provides a description of the following 

  • Installing Drools.NET
  • Drools.NET Features Description and their Usage
  • Running example applications.
  • Rule's Syntax 

    Each of these will be described in a different section of this document.

 

 

1.2       Business Vision

The Drools.NET is a .NET port for Drools, which is a Rules Engine implementation based on Charles Forgy's Rete algorithm tailored for the Java language. Drools.NET enables .NET developers/Users to exploit the powerful Rule Engine like Drools through a completely managed .NET code base. Rules can be written in any .NET language ((C#, VB.NET, J#, etc.) that can target the CLR. 

   

2          Drools.NET Installation 

 

2.1       System Requirements

Here are the system requirements for using Drools.NET:

  • .NET Framework v1.1 or v2.0. Drools.NET provides support for both v1.1 and v 2.0 of .NET Framework by using different builds for both of these.
  • IKVM 0.22.0.0 (http://www.ikvm.net) , included with the distribution
  • NUnit-2.2.2 or above (http://www.nunit.org), framework is included with the distribution
  • NUnit-GUI 2.2.2 or above to run the tests in a graphical environment  

2.2       Release Contents

Drools.NET release consists of the following

  • External Libraries:
    • drools-2.1.dll - The core drools assembly compiled using IKVM (IKVM is a compiler used to compile Java classes and jars into a .NET assembly)
    • IKVM.GNU.Classpath.dll - IKVM dependency required by the drools-2.1.dll assembly
    • IKVM.Runtime.dll - IKVM dependency required by the drools-2.1.dll assembly
    • nunit.framework.dll - Assembly required to create and run NUnit tests
  • Drools.NET Libraries
    • org.drools.dotnet.dll - Drools .NET wrapper classes
    • org.drools.dotnet.examples.dll - Drools .NET examples implemented as NUnit tests
    • org.drools.semantics.dotnet.dll - Drools .NET semantics layer
    • org.drools.dotnet.tests.dll - NUnit tests to test Drools.NET classes
    • /drls directory - The example rules definition files 
    • The source code for Drools.NET libraries and example drl files can be downloaded from CVS. The CVS download instructions can be found at http://drools.codehaus.org/CVS+Download+Instructions. The repository path for Drools.NET is /home/projects/drools/scm/drools/drools-dotnet..  

2.3       Installation

The Drools.NET BRE can be used in an application by referencing the following assemblies in an application:

  • drools-2.1.dll
  • IKVM.GNU.Classpath.dll
  • org.drools.dotnet.dll
  • org.drools.semantics.dotnet.dll



 

3          Drools.NET Features Description and Usage  

Drools.NET currently supports most of the features supported by Drools-2.1 and more.  

  • Basic features of Drools-2.1 - see the description at http://www.drools.org/
  • Support for Decision Tables
  • Support for Precompiled Rule-Bases - It enables a Rule-Base to be pre-compiled down to an assembly, that can be referenced in an application later to load the Rule-Base - no recompilation necessary. It is good for people who have very large Rule-Sets.
  • Support for Multiple .NET languages    

3.1       Using Basic Features of Drools

Drools.NET allows you to create, load and execute Rules in the same manner as it is done in drools-2.1.  

A class called 'RuleBaseLoader' provides functions for loading a Rule-Base from either one of these - a Stream, an Uri, an Assembly or a TextReader.  

A basic sequence of steps to use a RuleBase is as follows: 

//Step 1: include the following namespace

using org.drools.dotnet.io;

using org.drools.dotnet; 

//Step 2: Use RuleBaseLoader to load the RuleBase. Many convenience methods, as described in Section 3.1.1, are available to load a RuleBase. Here we are using 'loadFromStream' method

RuleBase ruleBase = RuleBaseLoader.loadFromStream(new FileInputStream("helloworld.csharp.drl.xml"));  

//Step 3: Get an instance of WorkingMemory for the loaded RuleBase

WorkingMemory workingMemory = ruleBase.GetNewWorkingMemory(); 

//Step 4: Assert facts

workingMemory.AssertObject("Hello"); 

//Step 5: Fire all Rules

workingMemory.FireAllRules();

 

 

3.1.1        RuleBaseLoader

'RuleBaseLoader' provides many convenience methods to load a RuleBase.

An example called RuleBaseLoaderTests is provided in 'org.drools.dotnet.tests.dll', which describes various ways to load a RuleBase.  

 Following code snippets are taken from that example: 

  • Loading a RuleBase from a Stream   RuleBase ruleBase = RuleBaseLoader.LoadFromStream(new

                                  FileStream("./drl/csharp.drl.xml"));

     
  • Loading a RuleBase from an Uri  RuleBase ruleBase = RuleBaseLoader.LoadFromUri(new Uri

                ("./drls/csharp.drl.xml", UriKind.Relative));

     
  • Loading a RuleBase from an Assembly  RuleBase ruleBase = RuleBaseLoader.LoadFromAssembly(

                                            this.GetType().Assembly);

     
  • Loading a RuleBase from a TextReader  RuleBase ruleBase = RuleBaseLoader.LoadFromReader(new                                

                             StreamReader("./drls/csharp.drl.xml")); 

Each of the above functions has overload methods that take ConflictResolver as an additional argument and that can load multiple rulesets by taking array of Streams, Uris and StreamReaders as argument.  

3.1.2        RuleBaseBuilder

TBD  

3.2       Drools.NET Decision Tables

Decision Tables in Drools.NET work similarly to decision tables in Drools. Please visit http://drools.codehaus.org/Decision+Tables, in order to get an understanding of how decision tables are used in drools.  

3.2.1        Getting Drools.NET Decision Tables working:

Using Drools.NET decision tables is very similar to the regular Drools.NET API. A class called 'DecisionTableLoader' defines functions for using decision-tables in .NET. Following is an example code snippet:

 //build a rule base

RuleBase rb = DecisionTableLoader.loadFromStream(streamToSpreadsheet);

//everything from here is just like normal Drools.NET

WorkingMemory engine = rb.GetNewWorkingMemory();

TestModel model =newTestModel ();

engine.AssertObject(model);

engine.FireAllRules(); 

  

3.2.2        Drools.NET v/s Drools Decision Tables:

 The only difference between the two decision tables is the language used for specifying conditions, consequences, functions etc. For Drools.NET, the language should be a .NET language, while in Drools Decision Tables it is Java.

 

3.2.3        Syntax of Decision Tables:

Decision Table's syntax in Drools.NET is exactly the same as Decision Tables in Drools.   

NOTE: If a class from an external library (not current working directory) is being referenced in a decision table, then its assembly name must be specified in the decision table with its declaration as follows: RuleTable allocateStream(org.drools.dotnet.examples.decisiontables.model.Claim.ASSEMBLY.org.drools.dotnet.examples claim)

 

The class name must be a fully classified name followed by string '.ASSEMBLY.' and then the assembly name. It ensures that the class gets loaded correctly.   

3.3       Pre-Compilation Support

Drools.NET provides support for pre-compiling a RuleBase in to an assembly. This assembly can be referenced directly in an application and be used without having to recompile the RuleBase. This feature is great for people with very large rulesets that takes a lot of time to compile.  Class 'RuleBaseLoader' provides functions to create and load Assemblies. Function 'LoadPrecompiledRulebase' takes a Stream/Uri to the rule file and the pre-compiled assembly name as arguments. It creates Rete network for the RuleSet and load the pre-compiled assembly. If it doesn't find the assembly, it creates a new one. The pre-compiled assembly is created in the CurrentDirectory, the directory from which the process has been started. Following code snippet shows the steps included in using pre-compiled assemblies:

//Step 1: include the following namespace

using org.drools.dotnet.io;

using org.drools.dotnet; 

//Step 2: Use RuleBaseLoader to load the Precompiled assembly escalation.dll. If the assembly doesn't exist, it will create one and save it for the future reference.

RuleBase ruleBase = RuleBaseLoader.LoadPrecompiledRulebase(new Uri(

                        "./drls/escalation.csharp.drl.xml", UriKind.Relative), "escalation.dll");  

//Step 3: Get an instance of WorkingMemory for the loaded RuleBase

WorkingMemory workingMemory = ruleBase.GetNewWorkingMemory(); 

//Step 4: Assert facts

workingMemory.AssertObject("Hello"); 

//Step 5: Fire all Rules

workingMemory.FireAllRules();

 

NOTE: In order to use a pre-compiled assembly in an application other than the one in which it is created, be sure to add a reference to the assembly. 

3.4       Support for Multiple .NET languages

Drools.NET provides support for multiple .NET languages. The .NET language for the rules can be changed by setting the value of "drools.dotnet.codedomprovider" in the appSettings configuration section. The value is the assembly qualified type name for the .NET code DOM provider to use.

By default, if the value is not present the C# provider is used. To change the rules language to VB.NET add the following to your web.config (web application) or app.config (all other .NET output types) <appSettings><add key=" drools.dotnet.codedomprovider "value=" Microsoft.VisualBasic.VBCodeProvider, System, Version=2.0.0.0,Culture=neutral, PublicKeyToken=b77a5c561934e089" /></appSettings> 

NOTE: The type name must include the assembly, version, culture, and public key token attributes! 

3.5       Support for .NET Framework v1.1 and 2.0

Drools.NET provides support for .NET Framework version 1.1 and 2.0. There is a separate Visual studio solution for each version. Each VS Project inside the VS solution has separate project files for each version.

   

4          Running Examples 

Drools.NET examples can be found in library 'org.drools.dotnet.examples.dll'. All the examples are implemented as NUnit tests, which can be run directly using NUnit GUI or Console application. They can also run in Visual Studio .NET.  

All of these examples are taken directly from drools-2.1 and have been ported to .NET. A description of these examples can be found at http://www.drools.org/Tutorials+and+Examples     

5          Known Issues  

TBD   

6          Future Work and Enhancements  

TBD