JBoss.orgCommunity Documentation

Drools Introduction and General User Guide

I've always stated that end business users struggle understanding the differences between rules and processes, and more recently rules and event processing. For them they have this problem in their mind and they just want to model it using some software. The traditional way of using two vendor offerings forces the business user to work with a process oriented or rules oriented approach which just gets in the way, often with great confusion over which tool they should be using to model which bit.

PegaSystems and Microsoft have done a great job of showing that the two can be combined and a behavioural modelling approach can be used. This allows the business user to work more naturally where the full range of approaches is available to them, without the tools getting in the way. From being process oriented to rule oriented or shades of grey in the middle - whatever suites the problem being modelled at that time.

Drools 5.0 takes this one step further by not only adding BPMN2 based workflow with Drools Flow but also adding event processing with Drools Fusion, creating a more holistic approach to software development. Where the term holistic is used for emphasizing the importance of the whole and the interdependence of its parts.

Drools 5.0 is now split into 5 modules, each with their own manual - Guvnor (BRMS/BPMS), Expert (Rules), Fusion (CEP), Flow (Process/Workflow) and Planner. Guvnor is our web based governance system, traditionally referred to in the rules world as a BRMS. We decided to move away from the BRMS term to a play on governance as it's not rules specific. Expert is the traditional rules engine. Fusion is the event processing side, it's a play on data/sensor fusion terminology. Flow is our workflow module, Kris Verlaenen leads this and has done some amazing work; he's currently moving flow to be incorporated into jBPM 5. The fith module called Planner, authored by Geoffrey De Smet, solves allocation and scheduling type problem and while still in the early stage of development is showing a lot of promise. We hope to add Semantics for 2011, based around description logc, and that is being work on as part of the next generaion Drools designs.

I've been working in the rules field now for around 7 years and I finally feel like I'm getting to grips with things and ideas are starting to gel and the real innovation is starting to happen. To me It feels like we actually know what we are doing now, compared to the past where there was a lot of wild guessing and exploration. I've been working hard on the next generation Drools Expert design document with Edson Tirelli and Davide Sottara. I invite you to read the document and get involved, http://community.jboss.org/wiki/DroolsLanguageEnhancements. The document takes things to the next level pushing Drools forward as a hybrid engine, not just a capable production rule system, but also melding in logic programming (prolog) with functional programming and description logic along with a host of other ideas for a more expressive and modern feeling language.

I hope you can feel the passion that my team and I have while working on Drools, and that some of it rubs off on you during your adventures.

A couple of maven artifacts (jars, wars, ...) have been renamed so it is more clear what they do. Below is the list of the GAV changes, adjust your pom.xml files accordingly when upgrading to the new version.

Table 2.1. Maven GAV changes overview

Old groupIdOld artifactIdNew groupIdNew artifactId
org.droolsdrools (the parent pom)org.droolsdroolsjbpm-parent
org.droolsdrools-examples-fusion / drools-examples-drl (jBPM using parts)org.droolsdroolsjbpm-integration-examples

For example: before, in your pom.xml files, you declared drools-api like this:


And now, afterwards, in your pom.xml files, you declare knowledge-api like this instead:


Drools now provides Prolog style derivation queries, as an experimental feature. What this means is that a query or the 'when' part of a rule may call a query, via a query element. This is also recursive so that a query may call itself. A query element must be prefixed with a question mark '?' which indicuates that we have a pattern construct that will pull data, rather than the normal reactive push nature of patterns.

A key aspect of BC is unification. This is where a query parameter may be bound or unbound, when unbound it is considered an output variable and will bind to each found value.

In the example below x and y are parameters. Unification is done by subsequent bindings inside of patterns. If a value for x is passed in, it's as though the pattern says "thing == x". If a value for x is not passed in it's as though "x: thing" and x will be bound to each found thing.

declare Location
    thing : String 
    location : String 

query isContainedIn( String x, String y ) 
    Location( x : thing, y : location)
    ( Location(z : thing, y : location) and ?isContainedIn(x : thing, z : location) )

Positional and mixed positional/named are supported.

declare Location
    thing : String 
    location : String 

query isContainedIn( String x, String y ) 
    Location(x, y;)
    ( Location(z, y;) and ?isContainedIn(x, z;) )

Here is an example of query element inside of a rule using mixed positional/named arguments.

query whereFood( String thing, String location ) 
    ( Location(thing, location;) and
      Edible(thing;) )
    ( Location(thing, location;) and
      TastesYucky(thing;) ) 

query look(String place, List things, List food, List exits) 
    things : List() from accumulate( Location(thing, place;),
                                    collectList( thing ) )
    food : List() from accumulate( ?whereFood(thing, place;) ,                                    
                                   collectList( thing ) )
    exits : List() from accumulate( ?connect(place, exit;),
                                    collectList( exit ) )

rule reactiveLook when
    Here( place : place) 
    ?look($place, $things; $food : food, $exits : exits)
    System.out.println( "You are in the " + $place);
    System.out.println( "  You can see " + $things );
    System.out.println( "  You can eat " + $food );
    System.out.println( "  You can go to " + $exits );

Literal expressions can passed as query arguments, but at this stage you cannot mix expressions with variables.

The other aspect to be aware of is that the implementation still executes with method recursion, so deeply recursive queries may have problems. Work is underway to an alternative algorithm that resolves this issue.


Further extension has been made to the decision table's featureset.

The existing Guided Decision Table has been replaced to provide a foundation on which to build our future guided Decision Table toolset. The initial release largely provides an equivalent feature-set to the obsolete Guided Decision Table with a few improvements, as explained in more detail below. A change from the legacy table was essential for us to begin to realise our desire to provide the number one web-based decision table available. With this foundation we will be able to expand the capabilities of our Guided Decision Table toolset to provide a feature rich, user-friendly environment.

Drools now has extensive Spring support, the XSD can be found in the the drools-spring jar. The namespace is "http://drools.org/schema/drools-spring"

Example 2.2. KnowledgeBuilder example

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
                           http://drools.org/schema/drools-spring http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/drools-container/drools-spring/src/main/resources/org/drools/container/spring/drools-spring-1.0.0.xsd
                           http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd">
  <drools:resource id="resource1" type="DRL" source="classpath:org/drools/container/spring/testSpring.drl"/>

  <drools:kbase id="kbase1">
      <drools:resource type="DRL" source="classpath:org/drools/container/spring/testSpring.drl"/>
      <drools:resource ref="resource1"/>
      <drools:resource source="classpath:org/drools/container/spring/IntegrationExampleTest.xls" type="DTABLE">
        <drools:decisiontable-conf input-type="XLS" worksheet-name="Tables_2" />

      <drools:mbeans enabled="true" />
      <drools:event-processing-mode mode="STREAM" />

KnowledgeBase takes the following configurations: "advanced-process-rule-integration, multithread, mbeans, event-processing-mode, accumulate-functions, evaluators and assert-behavior".

From the the kbase reference ksessions can be created

Like KnowledgeBases Knowlege sessions can take a number of configurations, including "work-item-handlers, "keep-references", "clock-type", "jpa-persistence".

StatefulKnowledgeSessions can be configured for JPA persistence

Example 2.5. JPA configuration for StatefulKnowledgeSessions

<bean id="ds" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
  <property name="driverClassName" value="org.h2.Driver" />
  <property name="url" value="jdbc:h2:tcp://localhost/DroolsFlow" />
  <property name="username" value="sa" />
  <property name="password" value="" />

<bean id="myEmf" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
  <property name="dataSource" ref="ds" />
  <property name="persistenceUnitName" value="org.drools.persistence.jpa.local" />

<bean id="txManager" class="org.springframework.orm.jpa.JpaTransactionManager">
  <property name="entityManagerFactory" ref="myEmf" />

<drools:ksession id="jpaSingleSessionCommandService" type="stateful" kbase="kbase1">
      <drools:transaction-manager ref="txManager" />
      <drools:entity-manager-factory ref="myEmf" />
         <drools:persister for-class="javax.persistence.Entity" implementation="org.drools.persistence.processinstance.persisters.JPAVariablePersister"/>
         <drools:persister for-class="java.lang.String" implementation="org.drools.container.spring.beans.persistence.StringVariablePersister"/>
         <drools:persister for-class="java.io.Serializable" implementation="org.drools.persistence.processinstance.persisters.SerializableVariablePersister"/>

Knowledge Sessions can support startup batch scripts, previous versions used the "script" element name, this will be updated to "batch". The following commands are supported: "insert-object", "set-global", "fire-all-rules", "fire-until-halt", "start-process", "signal-event". Anonymous beans or named "ref" attributes may be used.

ExecutionNodes are supported in Spring , these provide a Context of registered ksessions; this can be used with Camel to provide ksession routing.

Spring can be combined with Camel to provide declarative rule services. a Camel Policy is added from Drools which provides magic for injecting the ClassLoader used by the ksession for any data formatters, it also augments the Jaxb and XStream data formatters. In the case lf Jaxb it adds additional Drools related path info and with XStream it registers Drools related converters and aliases.

You can create as many endpoints as you require, using different addresses. The CommandMessagBodyReader is needed to allow the payload to be handled by Camel.

Camel routes can then be attached to CXF endpoints, allowing you control over the payload for things like data formatting and executing against Drools ksessions. The DroolsPolicy adds some smarts to the route. If JAXB or XStream are used, it would inject custom paths and converters, it can also set the classloader too on the server side, based on the target ksession. On the client side it automatically unwrapes the Response object.

This example unmarshalls the payload using an augmented XStream DataFormat and executes it against the ksession1 instance. The "node" there refers to the ExecutionContext, which is a context of registered ksessions.

The Drools endpoint "drools:node/ksession1" consists of the execution node name followed by a separator and optional knowledge session name. If the knowledge session is not specified the route will look at the "lookup" attribute on the incoming payload instace or in the head attribute "DroolsLookup" to find it.

Drools has always had query support, but the result was returned as an iterable set; this makes it hard to monitor changes over time.

We have now complimented this with Live Querries, which has a listener attached instead of returning an iterable result set. These live querries stay open creating a view and publish change events for the contents of this view. So now you can execute your query, with parameters and listen to changes in the resulting view.

A Drools blog article contains an example of Glazed Lists integration for live queries,


Rule's now suport both interval and cron based timers, which replace the now deprecated duration attribute.

Interval "int:" timers follow the JDK semantics for initial delay optionally followed by a repeat interval. Cron "cron:" timers follow standard cron expressions:

Calendars can now controll when rules can fire. The Calendar api is modelled on Quartz http://www.quartz-scheduler.org/ :

Calendars are registered with the StatefulKnowledgeSession:

They can be used in conjunction with normal rules and rules including timers. The rule calendar attribute can have one or more comma calendar names.

Appearance has been cleaned, for example less pop ups. Reminders for save after changes in assets and information about actions that were taken, also better error reporting if something goes wrong.

Guided Editor has basic support for From, Accumulate and Collect Patterns. You can add any of these structures as regular Patterns. New expression builder component was created to add support for nested method calls of a variable. Using the “plus” button at the top of rule’s WHEN section or using the new “Add after” button present in every Pattern will open the popup to add new conditional elements to your rule. In the list of possible elements you will find three new entries: ”From”, “From Accumulate” and “From Collect”.

When you add a new “From” element, you will see something like the image below in the guided editor. The left pattern of the “From” conditional element is a regular Pattern. You can add there any type of conditional element you want.The right section of the “From” pattern is an expression builder.

When using 'from collect' In the left pattern you can choose from “java.util.Collection”, “java.util.List” or “java.util.Set” Fact Types. This Fact Types will be automatically included in the package’s Fact Types list.

The right pattern of the collect conditional element could be one of this patterns:

  • Fact Type Pattern

  • Free Form Expression

  • From Pattern

  • From Collect Pattern

  • From Accumulate Pattern

When using 'from accumulate' The left pattern could be any Fact Type Pattern. The right section of this conditional element is splited in two:

The left pattern could be any Fact Type Pattern. The right section of this conditional element is splited in two:

  • Source Pattern: (Bed $n, in the screenshot) could be any Fact Type, From, Collect or Accumulate pattern.

  • Accumulate function: Here you will find a tabbed panel where you can enter an accumulate function (sum() in the screenshot) or you can create an online custom function using the “Custom Code” tab.

Drools now has complete api/implementation separation that is no longer rules oriented. This is an important strategy as we move to support other forms of logic, such as workflow and event processing. The main change is that we are now knowledge oriented, instead of rule oriented. The module drools-api provide the interfaces and factories and we have made pains to provide much better javadocs, with lots of code snippets, than we did before. Drools-api also helps clearly show what is intended as a user api and what is just an engine api, drools-core and drools-compiler did not make this clear enough. The most common interfaces you will use are:

Factory classes, with static methods, provide instances of the above interfaces. A pluggable provider approach is used to allow provider implementations to be wired up to the factories at runtime. The Factories you will most commonly used are:

A Typical example to load a process resource. Notice the ResourceType is changed, in accordance with the Resource type:

'kbuilder', 'kbase', 'ksession' are the variable identifiers often used, the k prefix is for 'knowledge'.

It is also possible to configure a KnowledgeBase using configuration, via a xml change set, instead of programmatically.

The other big change for the KnowledgeAgent, compared to the RuleAgent, is that polling scanner is now a service. further to this there is an abstraction between the agent notification and the resource monitoring, to allow other mechanisms to be used other than polling.

There are two new interfaces added, ResourceChangeNotifier and ResourceChangeMonitor. KnowlegeAgents subscribe for resource change notifications using the ResourceChangeNotifier implementation. The ResourceChangeNotifier is informed of resource changes by the added ResourceChangeMonitors. We currently only provide one out of the box monitor, ResourceChangeScannerService, which polls resources for changes. However the api is there for users to add their own monitors, and thus use a push based monitor such as JMS.

ResourceFactory.getResourceChangeNotifierService().addResourceChangeMonitor( myJmsMonitor);

In addition to the ability of configuring options in drools through configuration files, system properties and by setting properties through the API setProperty() method, Drools-API now supports type safe configuration. We didn't want to add specific methods for each possible configuration methods for two reasons: it polutes the API and every time a new option is added to Drools, the API would have to change. This way, we followed a modular, class based configuration, where a new Option class is added to the API for each possible configuration, keeping the API stable, but flexible at the same time. So, in order to set configuration options now, you just need to use the enumerations or factories provided for each option. For instance, if you want to configure the knowledge base for assert behavior "equality" and to automatically remove identities from pattern matchings, you would just use the enums:

For options that don't have a predefined constant or can assume multiple values, a factory method is provided. For instance, to configure the alpha threshold to 5, just use the "get" factory method:

As you can see, the same setOption() method is used for the different possible configurations, but they are still type safe.

Batch Executor allows for the scripting of of a Knowledge session using Commands, which can also re, both the StatelessKnowledgeSession and StatefulKnowledgeSession implement this interface Commands are created using the CommandFactory and executed using the "execute" method, such as the following insert Command:

Typically though you will want to execute a batch of commands, this can be achieved via the composite Command BatchExecution. BatchExecutionResults is now used to handle the results, some commands can specify "out" identifiers which it used to add the result to the BatchExecutionResult. Handily querries can now be executed and results added to the BatchExecutionResult. Further to this results are scoped to this execute call and return via the BatchExecutionResults:

The CommandFactory details the supported commands, all of which can marshalled using XStream and the BatchExecutionHelper. This can be combined with the pipeline to automate the scripting of a session.

Using the above for a rulset that updates the price of a Cheese fact, given the following xml to insert a Cheese instance using an out-identifier:

We then get the following BatchExecutionResults:

The MarshallerFactory is used to marshal and unmarshal StatefulKnowledgeSessions. At the simplest it can be used as follows:

However with marshalling you need more flexibility when dealing with referenced user data. To achieve this we have the ObjectMarshallingStrategy interface. Two implementations are provided, but the user can implement their own. The two supplied are IdentityMarshallingStrategy and SerializeMarshallingStrategy. SerializeMarshallingStrategy is the default, as used in the example above and it just calls the Serializable or Externalizable methods on a user instance. IdentityMarshallingStrategy instead creates an int id for each user object and stores them in a Map the id is written to the stream. When unmarshalling it simply looks to the IdentityMarshallingStrategy map to retrieve the instance. This means that if you use the IdentityMarshallingStrategy it's stateful for the life of the Marshaller instance and will create ids and keep references to all objects that it attempts to marshal.

For added flexability we can't assume that a single strategy is suitable for this we have added the ObjectMarshallingStrategyAcceptor interface that each ObjectMarshallingStrategy has. The Marshaller has a chain of strategies and when it attempts to read or write a user object it iterates the strategies asking if they accept responsability for marshalling the user object. One one implementation is provided the ClassFilterAcceptor. This allows strings and wild cards to be used to match class names. The default is "*.*", so in the above the IdentityMarshallingStrategy is used which has a default "*.*" acceptor. But lets say we want to serialise all classes except for one given package, where we will use identity lookup, we could do the following:

The KnowlegeAgent is created by the KnowlegeAgentFactory. The KnowlegeAgent provides automatic loading, caching and re-loading, of resources and is configured from a properties files. The KnowledgeAgent can update or rebuild this KnowlegeBase as the resources it uses are changed. The strategy for this is determined by the configuration given to the factory, but it is typically pull based using regular polling. We hope to add push based updates and rebuilds in future versions. The Following example constructs an agent that will build a new KnowledgeBase from the files specified in the path String. It will poll those files every 30 seconds to see if they are updated. If new files are found it will construct a new KnowledgeBase, instead of updating the existing one, due to the "newInstance" set to "true" (however currently only the value of "true" is supported and is hard coded into the engine):

Example 2.43. Constructing an agent

// Set the interval on the ResourceChangeScannerService if you are to use it and default of 60s is not desirable.
ResourceChangeScannerConfiguration sconf = ResourceFactory.getResourceChangeScannerService().newResourceChangeScannerConfiguration();
sconf.setProperty( "drools.resource.scanner.interval",
                  "30" ); // set the disk scanning interval to 30s, default is 60s
ResourceFactory.getResourceChangeScannerService().configure( sconf );
KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
KnowledgeAgentConfiguration aconf = KnowledgeAgentFactory.newKnowledgeAgentConfiguration();
aconf.setProperty( "drools.agent.scanDirectories",
                  "true" ); // we want to scan directories, not just files, turning this on turns on file scanning
aconf.setProperty( "drools.agent.newInstance",
                  "true" ); // resource changes results in a new instance of the KnowledgeBase being built,
                            // this cannot currently be set to false for incremental building
KnowledgeAgent kagent = KnowledgeAgentFactory.newKnowledgeAgent( "test agent", // the name of the agent
                                                                kbase, // the KnowledgeBase to use, the Agent will also monitor any exist knowledge definitions
                                                                aconf );
kagent.applyChangeSet( ResourceFactory.newUrlResource( url ) ); // resource to the change-set xml for the resources to add

KnowledgeAgents can take a empty KnowledgeBase or a populated one. If a populated KnowledgeBase is provided, the KnowledgeAgent will iterate KnowledgeBase and subscribe to the Resource that it finds. While it is possible for the KnowledgeBuilder to build all resources found in a directory, that information is lost by the KnowledgeBuilder so those directories will not be continuously scanned. Only directories specified as part of the applyChangeSet(Resource) method are monitored.

Drools 4.0 had simple "RuleFlow" which was for orchestrating rules. Drools 5.0 introduces a powerful (extensible) workflow engine. It allows users to specify their business logic using both rules and processes (where powerful interaction between processes and rules is possible) and offers a unified enviroment.

Drools 5.0 brings to the rules world the full power of events processing by supporting a number of CEP features as well as supporting events as first class citizens in the rules engine.

Drools 4.0 is a major update over the previous Drools 3.0.x series. A whole new set of features were developed which special focus on language expressiveness, engine performance and tools availability. The following is a list of the most interesting changes.

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.

Drools provides an Eclipse-based IDE (which is optional), but at its core only Java 1.5 (Java SE) is required.

A simple way to get started is to download and install the Eclipse plug-in - this will also require the Eclipse GEF framework to be installed (see below, if you don't have it installed already). This will provide you with all the dependencies you need to get going: you can simply create a new rule project and everything will be done for you. Refer to the chapter on the Rule Workbench and IDE for detailed instructions on this. Installing the Eclipse plug-in is generally as simple as unzipping a file into your Eclipse plug-in directory.

Use of the Eclipse plug-in is not required. Rule files are just textual input (or spreadsheets as the case may be) and the IDE (also known as the Rule Workbench) is just a convenience. People have integrated the rule engine in many ways, there is no "one size fits all".

Alternatively, you can download the binary distribution, and include the relevant jars in your projects classpath.

Drools is broken down into a few modules, some are required during rule development/compiling, and some are required at runtime. In many cases, people will simply want to include all the dependencies at runtime, and this is fine. It allows you to have the most flexibility. However, some may prefer to have their "runtime" stripped down to the bare minimum, as they will be deploying rules in binary form - this is also possible. The core runtime engine can be quite compact, and only require a few 100 kilobytes across 2 jar files.

The following is a description of the important libraries that make up JBoss Drools

There are quite a few other dependencies which the above components require, most of which are for the drools-compiler, drools-jsr94 or drools-decisiontables module. Some key ones to note are "POI" which provides the spreadsheet parsing ability, and "antlr" which provides the parsing for the rule language itself.

NOTE: if you are using Drools in J2EE or servlet containers and you come across classpath issues with "JDT", then you can switch to the janino compiler. Set the system property "drools.compiler": For example: -Ddrools.compiler=JANINO.

For up to date info on dependencies in a release, consult the released poms, which can be found on the maven repository.

The rule workbench (for Eclipse) requires that you have Eclipse 3.4 or greater, as well as Eclipse GEF 3.4 or greater. You can install it either by downloading the plug-in or, or using the update site.

Another option is to use the JBoss IDE, which comes with all the plug-in requirements pre packaged, as well as a choice of other tools separate to rules. You can choose just to install rules from the "bundle" that JBoss IDE ships with.

Download the Drools Eclipse IDE plugin from the link below. Unzip the downloaded file in your main eclipse folder (do not just copy the file there, extract it so that the feature and plugin jars end up in the features and plugin directory of eclipse) and (re)start Eclipse.


To check that the installation was successful, try opening the Drools perspective: Click the 'Open Perspective' button in the top right corner of your Eclipse window, select 'Other...' and pick the Drools perspective. If you cannot find the Drools perspective as one of the possible perspectives, the installation probably was unsuccessful. Check whether you executed each of the required steps correctly: Do you have the right version of Eclipse (3.4.x)? Do you have Eclipse GEF installed (check whether the org.eclipse.gef_3.4.*.jar exists in the plugins directory in your eclipse root folder)? Did you extract the Drools Eclipse plugin correctly (check whether the org.drools.eclipse_*.jar exists in the plugins directory in your eclipse root folder)? If you cannot find the problem, try contacting us (e.g. on irc or on the user mailing list), more info can be found no our homepage here:


A Drools runtime is a collection of jars on your file system that represent one specific release of the Drools project jars. To create a runtime, you must point the IDE to the release of your choice. If you want to create a new runtime based on the latest Drools project jars included in the plugin itself, you can also easily do that. You are required to specify a default Drools runtime for your Eclipse workspace, but each individual project can override the default and select the appropriate runtime for that project specifically.

You are required to define one or more Drools runtimes using the Eclipse preferences view. To open up your preferences, in the menu Window select the Preferences menu item. A new preferences dialog should show all your preferences. On the left side of this dialog, under the Drools category, select "Installed Drools runtimes". The panel on the right should then show the currently defined Drools runtimes. If you have not yet defined any runtimes, it should like something like the figure below.

To define a new Drools runtime, click on the add button. A dialog as shown below should pop up, requiring the name for your runtime and the location on your file system where it can be found.

In general, you have two options:

After clicking the OK button, the runtime should show up in your table of installed Drools runtimes, as shown below. Click on checkbox in front of the newly created runtime to make it the default Drools runtime. The default Drools runtime will be used as the runtime of all your Drools project that have not selected a project-specific runtime.

You can add as many Drools runtimes as you need. For example, the screenshot below shows a configuration where three runtimes have been defined: a Drools 4.0.7 runtime, a Drools 5.0.0 runtime and a Drools 5.0.0.SNAPSHOT runtime. The Drools 5.0.0 runtime is selected as the default one.

Note that you will need to restart Eclipse if you changed the default runtime and you want to make sure that all the projects that are using the default runtime update their classpath accordingly.

Whenever you create a Drools project (using the New Drools Project wizard or by converting an existing Java project to a Drools project using the "Convert to Drools Project" action that is shown when you are in the Drools perspective and you right-click an existing Java project), the plugin will automatically add all the required jars to the classpath of your project.

When creating a new Drools project, the plugin will automatically use the default Drools runtime for that project, unless you specify a project-specific one. You can do this in the final step of the New Drools Project wizard, as shown below, by deselecting the "Use default Drools runtime" checkbox and selecting the appropriate runtime in the drop-down box. If you click the "Configure workspace settings ..." link, the workspace preferences showing the currently installed Drools runtimes will be opened, so you can add new runtimes there.

You can change the runtime of a Drools project at any time by opening the project properties (right-click the project and select Properties) and selecting the Drools category, as shown below. Check the "Enable project specific settings" checkbox and select the appropriate runtime from the drop-down box. If you click the "Configure workspace settings ..." link, the workspace preferences showing the currently installed Drools runtimes will be opened, so you can add new runtimes there. If you deselect the "Enable project specific settings" checkbox, it will use the default runtime as defined in your global preferences.

Drools is available from two Subversion repositories.

To checkout Drools source code just execute the following command.
fmeyer:~/jboss $ svn checkout http://anonsvn.jboss.org/repos/labs/labs/jbossrules/trunk/ trunk
And wait to complete the files download.
A    trunk/drools-repository
A    trunk/drools-repository/.classpath
A    trunk/drools-repository/.project
A    trunk/drools-repository/doc
A    trunk/drools-repository/doc/repository_layout.jpeg
A    trunk/drools-repository/doc/high_level_design.jpeg
A    trunk/drools-repository/doc/javadoc
A    trunk/drools-repository/doc/javadoc/serialized-form.html
A    trunk/drools-repository/doc/javadoc/index-all.html
A    trunk/drools-repository/doc/javadoc/stylesheet.css
A    trunk/drools-repository/doc/javadoc/allclasses-frame.html
A    trunk/drools-repository/doc/javadoc/package-list
A    trunk/drools-repository/doc/javadoc/overview-tree.html
A    trunk/drools-repository/doc/javadoc/org
A    trunk/drools-repository/doc/javadoc/org/drools
A    trunk/drools-repository/doc/javadoc/org/drools/repository
A    trunk/drools-repository/doc/javadoc/org/drools/repository/class-use
A    trunk/drools-repository/doc/javadoc/org/drools/repository/class-use/RuleSet.html
A    trunk/drools-repository/doc/javadoc/org/drools/repository/class-use/RulesRepositoryException.html
A    trunk/drools-repository/doc/javadoc/org/drools/repository/class-use/RulesRepository.html
A    trunk/drools-repository/doc/javadoc/org/drools/repository/RuleSet.html




A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/waltz
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/waltz/waltz.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/manners
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/manners/manners.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/waltzdb
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/benchmark/waltzdb/waltzdb.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/TroubleTicketWithDSL.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/TroubleTicket.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/calculate.rfm
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/generation.rf
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/calculate.rf
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/registerNeighbor.rfm
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/killAll.rfm
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/registerNeighbor.rf
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/conway-agendagroup.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/killAll.rf
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/conway-ruleflow.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/conway/generation.rfm
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/ticketing.dsl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/StateExampleUsingSalience.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/golf.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/StateExampleDynamicRule.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/sudoku
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/sudoku/sudoku.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/HelloWorld.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/ExamplePolicyPricing.xls
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/HonestPolitician.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/Fibonacci.drl
A    trunk/drools-examples/drools-expert-examples/src/main/rules/org/drools/examples/StateExampleUsingAgendGroup.drl
A    trunk/drools-examples/drools-expert-examples/pom.xml
A    trunk/drools-examples/drools-expert-examples/build.xml
 U   trunk
Checked out revision 13656.

Although, we highly recommend command line tools to work with repository you can also use both Eclipse's integrated SVN client or TortoiseSVN

Setup TortoiseSVN to checkout from the subversion repository and click OK. Once the checkout has finished you should see the folders as shown below.

Now that we have the source the next step is to build and install the source. Since version 3.1 Drools uses Maven 2 to build the system. There are two profiles available which enable the associated modules "documentation" and "Eclipse"; this enables quicker building of the core modules for developers. The Eclipse profile will download Eclipse into the drools-Eclipse folder, which is over 100MB download (It depends on your operating system), however this only needs to be done once; if you wish you can move that Eclipse download into another location and specify it with -DlocalEclipseDrop=/folder/jboss-drools/local-Eclipse-drop-mirror. The following builds all the jars, the documentation and the Eclipse zip with a local folder specified to avoid downloading Eclipse:

mvn -Declipse -Ddocumentation clean install -DlocalEclipseDrop=/folder/jboss-drools/local-Eclipse-drop-mirror

You can produce distribution builds, which puts everything into zips, as follows:

mvn -Declipse -Ddocumentation clean install -DlocalEclipseDrop=/folder/jboss-drools/local-Eclipse-drop-mirror
mvn -Ddocumentation -Declipse -DskipTests package javadoc:javadoc assembly:assembly -DlocalEclipseDrop=/folder/jboss-drools/local-Eclipse-drop-mirror

Note that install must be done first as javadoc:javadoc won't work unless the jars are in the local maven repo, but the tests can be skipped on the second run. assembly:assembly fails unless you increase the available memory to Maven, on windows the following command worked well: set MAVEN_OPTS=-Xmx512m

Type mvn clean to clear old artifacts, and then test and built the source, and report on any errors.

The resulting jars are put in the /target directory from the top level of the project.

As maven builds each module it will install the resulting jars in the local Maven 2 repository automatically. Where it can be easily used from other project pom.xml or copied else where.

The building of the manual is now integrated into the maven build process, and is built by either using the profile (-Ddocumentation) switch or cding into the main directory.

Drools uses Docbook for this manual. Maven is used to build documents and this build produces three different formats, all sharing the same images directory.

The manual can be generated from the project pom.xml by calling mvn package in the drools-docs directory or adding the -Ddocumentation switch when you build the sources. Documentation is generated into each drools-docs subdirectory's target/ directory. Running mvn -Ddocumentation package assembly:assembly in the Drools project root generates and copies the documentation into a zip file. This zip file is located in the root folders target/ directory.

[trikkola@trikkola trunk]$ mvn -Ddocumentation clean package assembly:assembly
[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO]   Drools
[INFO]   Drools :: API
[INFO]   Drools :: Core
[INFO]   Drools :: Compiler
[INFO]   Drools :: Templates
[INFO]   Drools :: Decision Tables
[INFO]   Drools :: JSR-94 API Module
[INFO]   Drools :: Pipeline :: Transformer :: Smooks
[INFO]   Drools :: Pipeline :: Transformer :: JAXB
[INFO]   Drools :: Pipeline :: Transformer :: XStream
[INFO]   Drools :: Pipeline :: Transformer :: JXLS
[INFO]   Drools :: Pipeline :: Messenger :: JMS
[INFO]   Drools :: Pipeline
[INFO]   Drools :: Process :: WorkItems
[INFO]   Drools :: Process :: Task
[INFO]   Drools :: Process :: BAM
[INFO]   Drools :: Process
[INFO]   Drools :: Persistence :: JPA
[INFO]   Drools :: Server
[INFO]   Drools :: Verifier
[INFO]   Drools :: Ant Task
[INFO]   Drools :: Repository
[INFO]   Drools :: Guvnor
[INFO]   Drools :: Microcontainer
[INFO]   Drools :: Clips
[INFO]   Drools :: Planner parent
[INFO]   Drools :: Planner core
[INFO]   Drools :: Planner examples
[INFO] Searching repository for plugin with prefix: 'assembly'.
WAGON_VERSION: 1.0-beta-2
[INFO] ------------------------------------------------------------------------
[INFO] Building Drools
[INFO]    task-segment: [clean, package]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] [site:attach-descriptor]
[INFO] Preparing source:jar
[WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation.
[INFO] No goals needed for project - skipping
[INFO] [source:jar {execution: default}]
[INFO] Preparing source:test-jar
[WARNING] Removing: jar from forked lifecycle, to prevent recursive invocation.
[WARNING] Removing: test-jar from forked lifecycle, to prevent recursive invocation.
[INFO] No goals needed for project - skipping
[INFO] [source:test-jar {execution: default}]
[INFO] ------------------------------------------------------------------------
[INFO] Building Drools :: API
[INFO]    task-segment: [clean, package]
[INFO] ------------------------------------------------------------------------
[INFO] [clean:clean]
[INFO] Deleting directory /home/trikkola/jboss-drools/trunk/drools-api/target

...snip ...

[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] Drools ................................................ SUCCESS [59.889s]
[INFO] Drools :: API ......................................... SUCCESS [4.832s]
[INFO] Drools :: Core ........................................ SUCCESS [11.027s]
[INFO] Drools :: Compiler .................................... SUCCESS [10.400s]
[INFO] Drools :: Templates ................................... SUCCESS [1.018s]
[INFO] Drools :: Decision Tables ............................. SUCCESS [1.179s]
[INFO] Drools :: JSR-94 API Module ........................... SUCCESS [1.001s]
[INFO] Drools :: Pipeline :: Transformer :: Smooks ........... SUCCESS [0.651s]
[INFO] Drools :: Pipeline :: Transformer :: JAXB ............. SUCCESS [0.711s]
[INFO] Drools :: Pipeline :: Transformer :: XStream .......... SUCCESS [0.465s]
[INFO] Drools :: Pipeline :: Transformer :: JXLS ............. SUCCESS [0.481s]
[INFO] Drools :: Pipeline :: Messenger :: JMS ................ SUCCESS [0.879s]
[INFO] Drools :: Pipeline .................................... SUCCESS [0.006s]
[INFO] Drools :: Process :: WorkItems ........................ SUCCESS [1.526s]
[INFO] Drools :: Process :: Task ............................. SUCCESS [3.104s]
[INFO] Drools :: Process :: BAM .............................. SUCCESS [0.580s]
[INFO] Drools :: Process ..................................... SUCCESS [0.005s]
[INFO] Drools :: Persistence :: JPA .......................... SUCCESS [0.958s]
[INFO] Drools :: Server ...................................... SUCCESS [2.216s]
[INFO] Drools :: Verifier .................................... SUCCESS [1.836s]
[INFO] Drools :: Ant Task .................................... SUCCESS [0.722s]
[INFO] Drools :: Repository .................................. SUCCESS [3.925s]
[INFO] Drools :: Guvnor ...................................... SUCCESS [19.850s]
[INFO] Drools :: Microcontainer .............................. SUCCESS [0.676s]
[INFO] Drools :: Clips ....................................... SUCCESS [1.464s]
[INFO] Drools :: Planner parent .............................. SUCCESS [0.527s]
[INFO] Drools :: Planner core ................................ SUCCESS [2.209s]
[INFO] Drools :: Planner examples ............................ SUCCESS [4.689s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 2 minutes 24 seconds
[INFO] Finished at: Tue Apr 07 15:11:14 EEST 2009
[INFO] Final Memory: 48M/178M
[INFO] ------------------------------------------------------------------------>

The generated manual can be found in the target/drools-docs-$VERSION.jar file, a compressed archive with all formats.