JBoss.orgCommunity Documentation

Chapter 3. Installation and Setup (Core and IDE)

3.1. Installing and using
3.1.1. Dependencies and jars
3.1.2. Runtime
3.1.3. Installing IDE (Rule Workbench)
3.2. Setup from source
3.3. Source Checkout
3.4. Build
3.4.1. Building the Source
3.4.2. Building the Manual
3.5. Eclipse
3.5.1. Importing Eclipse Projects

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.

http://www.jboss.org/drools/downloads.html

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:

http://www.jboss.org/drools/

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.

As Drools is an open source project, instructions for building from source are part of the manual ! Building from source means you can stay on top with the latest features. Whilst aspects of Drools are quite complicated, many users have found ways to become contributors.

Drools works with JDK1.5 and above. you will need also need to have the following tools installed. Minimum requirement version numbers provided.

Ensure the executables for maven and java are in your path. The examples given illustrative and are for a win32 system:

Following environment variables will also need to be set. The examples given illustrative and are for a win32 system::

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

....

snip 

....

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] ------------------------------------------------------------------------
[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] BUILD SUCCESSFUL
[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.