JBossRules

Welcome to the wiki of page for JBoss Rules. Otherwise known as Drools 3.

 

PLEASE NOTE

Currently Drools 3 is in beta 1. This wiki page is serving as a quick introduction for early adopters.

  • There is a formal and official Manual in the works, which will be available very shortly.

  • There will be a rapid succession of betas for this product, as it has been in the works for some months. So make sure you check back and keep updated.

  • There are known issues which are being addressed in later beta releases. If you find a bug, please check http://jira.jboss.com/jira/browse/JBRULES to see if it has been reported - otherwise report it and let us know !

  • Known issues and features to be implemented can be seen via the JBoss jira

 

Distribution

  • The binary distribution can be downloaded from here. All dependencies you may need are there for your convenience.

    • Add the jars to your classpath, and then refer to the Samples section below for some tips on how to get started, and see linked examples.

  • Source can be accessed via anonymous Subversion: http://anonsvn.labs.jboss.com/trunk/labs/jbossrules/

    • You can use any SVN client, or browse it online.

    • The important modules are drools-core, drools-compiler and drools-ide

 

IDE/Eclipse plug in

 

Yes, there is a plug in.

  • You can download it from from here.

  • This is an ideal way to get started quickly if you are an Eclipse user.

  • Note that some of the language features are not fully implemented in the IDE (the downside is you may see errors being reported in otherwise valid rule files). DSLs/natural language extensions are not correctly supported either. This will be corrected in the next beta release.

Installing

This requires Eclipse 3.2 M5. Once you have Eclipse 3.2M5, you unzip the file (above) into your plugin directory, and restart the workbench.

Using

When you restart the workbench, you will see the rule icon (Mr Trout) on your toolbar. From that menu (or from the wizard menu) you can choose to create a new rule project (you get other choices too). When you create a new project, it will setup your classpath, and create a sample executable rule file. Look for Sample.drl and DroolsTest.java (which you can execute to make sure it all works).

 

 

Getting help or helping out

  • As normal, the maniacs can be found in the drools IRC room at irc.codehaus.org. Web client available for those behind a firewall http://irc.codehaus.org. Mark Proctor is known as "conan", and he is a vegetiarian, so he won't bite. The others are not though

  • Use the mailing list from http://www.drools.org as normal. Use the "user" list for end user issues, "dev" for when you are mucking about with the internals.

  • Use jira to log issues.

 

 

Samples

Its important to note that the default textual language input for Drools 3 is a non XML format (XML support will be coming shortly as an alternative). It uses an Antlr3 grammar to parse rules and compile.

 

Hello World

 

Following is a very basic hello world in vanilla DRL

package HelloWorld
 
import org.drools.integrationtests.helloworld.Message

rule "Hello World"
     when
          m : Message(list contains "hello") #collection support
          Message(message == "hola")
          Message(number > 40)
          Message(birthday > "10-Jul-1974") #date support
          Message(message matches ".*ho.*") #regular expression support
     then
          System.out.println("hello world " + m.getMessage());
          m.setFired(true); 
end

The hello world source code (java) to run the example is here

And the actual hello world rule input is here

 

 

Using a domain specific language extension (using the keyword "expander" in the rule source) you can have natural language style rules like the following:

rule "my rule"
     when
          There is a person with the name of Bob who likes stilton
          There is some stilton cheese available
     then
          Add the message "We have a winner"
end

Note that the IDE will be aware of the domain specific language extensions, and provide appropriate content assistance (popups). DSLs are handy as they allow you to tightly control how the rule language maps to your objects, and the actual rule language constructs (so you can easily refactor without having to change rules en-masse, or optimise the type of nodes that are being used in the conditions etc).

 

 

Rules are executed with the  following code:

            WorkingMemory workingMemory = ruleBase.newWorkingMemory();
            
            //load the data           
            Message message = new Message("hola");
            message.addToList( "hello" );
            message.setNumber( 42 );
            
            //assert it into the engine
            workingMemory.assertObject( message );
            workingMemory.assertObject( "boo" );
            workingMemory.fireAllRules();  

 

To load/compile the rules, see the following:

        //use package builder in this case to incrementally load up a rule base
        PackageBuilder builder = new PackageBuilder();
        builder.addPackageFromDrl( readerToSource );
        
        //this will compile/build/validate: you can serialize and deplou the "Package" object
        Package pkg = builder.getPackage();
                
        RuleBase ruleBase = RuleBaseFactory.newRuleBase(); //creates RETE by default
        ruleBase.addPackage( pkg ); //can have multiple packages if you like...
        WorkingMemory workingMemory = ruleBase.newWorkingMemory();       

 

 

More complete examples

 

  • A fairly comprehensive set of examples (actually the integration tests) can be browsed online here

    • The code to invoke these examples is here

 

 

Building from source

Drools 3 is in beta, and very much a moving target.

For those who want to stay up to date, working off source isn't that hard. Maven 2 is used as the build system. Here are some brief instructions on how to do it. If you run into trouble, join us on IRC or the mailing list for some pointers.

 

  1. Download and install maven 2 from here

    1. You may need to set your system path to include the maven bin directory

  2. Grab a SVN client. SVN is handy as it just works over HTTP. The anonymous SVN mirror is kept up to date with the live source. You can use SmartSVN, TorroiseSVN or Subclipse etc.

  3. Checkout the root of the project: http://anonsvn.labs.jboss.com/trunk/labs/jbossrules/

  4. Go into the root of the project and run maven: "mvn package". This will download all the dependencies, build and run tests.

    1. also run "mvn install" to install the application into your local repository if you wish.

  5. You can then run mvn eclipse:eclipse to generate eclipse projects for you (or you can go into drools-core for instance, and run it there to generate a project for just that module). Maven also supports IDEA and Netbeans in a similar fashion.

  6. If you are using an IDE, you can import the projects at that point. You will need to set an environment variable for "M2_REPO" which will point to the local directory that contains all the dependencies that maven manages for you (usually in your home directory). In Eclipse its Window/Preferences/Java/Build Path/Classpath Variables.

  7. That should be it.

 

Building the IDE/Plugin

If you want to work on the plug in source, it will already have a project and classpath file, just import it as an existing project into eclipse (also use 3.2 M5).

  • Running mvn package will also populate the dependency jars in the plug ins lib directory (hence the plug in comes with no jars of its own).

 

 

 

JBoss Rules (Drools 3.0) Feature list

  • A feature list can be found here