JBoss.orgCommunity Documentation

Chapter 2. Installation and Setup (Core and IDE)

2.1. Installing and using
2.1.1. Dependencies and jars
2.1.2. Runtime
2.1.3. Installing IDE (Rule Workbench)
2.2. Setup from source
2.3. Source Checkout
2.4. Build
2.4.1. Building the Source
2.4.2. Building the Manual
2.5. Eclipse
2.5.1. Generating Eclipse Projects
2.5.2. Importing Eclipse Projects
2.5.3. Exporting the IDE plug-in
2.5.4. Building the update site

Drools provides an Eclipse-based IDE (which is optional), but at its core only Java 1.4 (J2SE) 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 Rules

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 of these (such as the XML libraries) may not be required if you run in a Java 1.5 environment. Some key ones to note are "JCI" - which is the apache Java Compiler Interface utility which provides runtime compiling capability, "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 README_DEPENDENCIES.txt file, which can be found in the lib directory of the download bundle, or in the root of the project directory.

The rule workbench (for Eclipse) requires that you have Eclipse 3.2 or greater, as well as Eclipse GEF 3.2 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.

Using the update site is a handy way to install the plug-in, and keep it up to date (the Eclipse platform will check for updates as needed). It gives you a good chance of staying up to date with improvements, fixes etc.

Some firewalls may cause trouble with using update sites in Eclipse, if you have issues, then install it manually from the plug-in. Also, if you have previously installed the plug-in manually, you will need to manually remove it from your plug-in directory.

Step 1. Use the Eclipse help menu to find the feature installer.

Step 2: Choose the option for installing a new feature (obviously in future, if you want to check for updates, you use the other option !).

Step 3: This screen will show what update sites are already configured for your Eclipse instance.

Step 4: This screen is where you enter in the remote site details. You give it a name eg "JBoss Drools" and the url.

 Check the Drools IDE Update Site section of the Drools Downloads webpage: 
				http://labs.jboss.com/drools/downloads.html

Step 5: Select the new update site you just added. Eclipse will remember this for when it checks for updates automatically in the future.

Step 6: You should see the available features (Drools IDE) retrieved from the update site.

Step 7: The license agreement. Choose the option to accept the license agreement. Once this happens, the workbench will start downloading. Might be an opportune time to go have a coffee.

Step 8: Confirm that this is the feature you want.

Step 9: Press Accept to accept the fact that the feature is not digitally signed. No one signs their features, its a silly default screen in Eclipse.

Step 10: The workbench will need to restart now for the feature to take effect.

Now go have another coffee, and then take a look at the chapter on the Rule Workbench for what you can do with it.

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 ant, 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::

Past releases used to have an ant based build mechanism, but now maven is mandatory, although Ant is used internally in maven for document building proposes

Drools is available from two Subversion repositories.

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

....

snip 

....

A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/waltz
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/waltz/waltz.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/manners
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/manners/manners.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/waltzdb
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/benchmark/waltzdb/waltzdb.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/TroubleTicketWithDSL.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/TroubleTicket.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/calculate.rfm
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/generation.rf
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/calculate.rf
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/registerNeighbor.rfm
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/killAll.rfm
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/registerNeighbor.rf
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/conway-agendagroup.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/killAll.rf
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/conway-ruleflow.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/conway/generation.rfm
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/ticketing.dsl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/StateExampleUsingSalience.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/golf.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/LogicalAssertionsNotPingPong.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/StateExampleDynamicRule.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/sudoku
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/sudoku/sudoku.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/HelloWorld.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/ExamplePolicyPricing.xls
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/HonestPolitician.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/Fibonacci.drl
A    jbossrules/drools-examples/drools-examples-drl/src/main/rules/org/drools/examples/StateExampleUsingAgendGroup.drl
A    jbossrules/drools-examples/drools-examples-drl/pom.xml
A    jbossrules/drools-examples/drools-examples-drl/build.xml
 U   jbossrules
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 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-rules/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-rules/local-Eclipse-drop-mirror 

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

mvn -Declipse -Ddocumentation clean install -DlocalEclipseDrop=/folder/jboss-rules/local-Eclipse-drop-mirror
mvn -Ddocumentation -Declipse -Dmaven.test.skip package javadoc:javadoc assembly:assembly -DlocalEclipseDrop=/folder/jboss-rules/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. The manual can still be built from ant command line too by cding into the documentation/manual itself.

Drools uses Docbook for this manual. Ant is used internally in maven 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 documentation directory or adding the -Ddocumentation switch when you build the sources, with the generated documentation being copied to 'target/. What actually happens is that maven call a separate ant build.xml for the manual, located at documentation/manual; the documentation is generated into documentation/manual/build before being copied to 'target/'.

fmeyer:~/projects/jbossrules/documentation $ mvn clean package
[INFO] Scanning for projects...
[INFO] ----------------------------------------------------------------------------
[INFO] Building Drools :: Documentation
[INFO]    task-segment: [install]
[INFO] ----------------------------------------------------------------------------
[INFO] [antrun:run {execution: manual}]
[INFO] Executing tasks
 [delete] Deleting directory /Users/fernandomeyer/projects/jbossrules/documentation/manual/build

clean:

all.doc:

lang.all:

lang.misc:
   [copy] Copying 188 files to /Users/fernandomeyer/projects/jbossrules/documentation/manual/build/en/shared/images
   [copy] Copying 1 file to /Users/fernandomeyer/projects/jbossrules/documentation/manual/build/en/shared/css

lang.dochtml:
  [mkdir] Created dir: /Users/fernandomeyer/projects/jbossrules/documentation/manual/build/en/html
   [copy] Copying 1 file to /Users/fernandomeyer/projects/jbossrules/documentation/manual/build/en/html
   [java] Writing bk01-toc.html for book
   [java] Writing pr01.html for preface(preface)
   [java] Writing ch01s02.html for section
   [java] Writing ch01s03.html for section
   [java] Writing ch01s04.html for section
   [java] Writing ch01s05.html for section
   [java] Writing ch01s06.html for section
   [java] Writing ch01.html for chapter
   [java] Writing ch02s02.html for section
   [java] Writing ch02s03.html for section
   [java] Writing ch02s04.html for section
   [java] Writing ch02s05.html for section
   [java] Writing ch02.html for chapter
   [java] Writing ch03s02.html for section
   [java] Writing ch03s03.html for section
   [java] Writing ch03s04.html for section
   [java] Writing ch03s05.html for section
   [java] Writing ch03s06.html for section
   [java] Writing ch03s07.html for section
   [java] Writing ch03s08.html for section
   [java] Writing ch03s09.html for section
   [java] Writing ch03.html for chapter
   [java] Writing ch04.html for chapter
   [java] Writing ch05.html for chapter
   [java] Writing ch06s02.html for section
   [java] Writing ch06s03.html for section
   [java] Writing ch06s04.html for section
   [java] Writing ch06s05.html for section
   [java] Writing ch06.html for chapter
   [java] Writing ch07s02.html for section
   [java] Writing ch07s03.html for section
   [java] Writing ch07.html for chapter
   [java] Writing ch08.html for chapter
   [java] Writing ch09.html for chapter
   [java] Writing ch10s02.html for section
   [java] Writing ch10.html for chapter
   [java] Writing ch11.html for chapter
   [java] Writing pt01.html for part
   [java] Writing ix01.html for index
   [java] Writing title.html for book

...snip ...

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 51 seconds
[INFO] Finished at: Mon Jul 21 12:03:38 BRT 2007
[INFO] Final Memory: 5M/10M
[INFO] ------------------------------------------------------------------------>

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

The manual was first generated into the manual's build directory, as shown below, before being copied across.

There is also an update site for the plug-in. For developers who want to update the update site (ha) you will need to get to the update site project (or create a new one). They are kept in SVN, but in /jbossrules/update instead of /trunk. They are plain vanilla Eclipse feature and site projects.

PLEASE REMEMBER that the plug-in in the downloads directory, as a zip, should also be updated at the same time as the update site (as they are alternative ways ot getting the same plug-in).

Eclipse refreshing plug-ins in features and sites seems to not work, so what is best is to manually edit the site.xml project and the feature.xml. To do this, open the site.xml file in the drools-ide-update project, it should look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<site>
   <!-- change both the jar and the version number, make sure the new features jar is named
        the same as what you put in -->
   <feature url="features/org.drools.ide_1.0.2.jar" id="org.drools.ide" version="1.0.2">
  <category name="JBossRules"/>
   </feature>
   <category-def name="JBossRules" label="JBoss Rules"/>
</site>

Change the version attribute to be something new, and also the name of the feature jar to have a new version number at the end.

Go into the /feature directory, and unzip the feature jar to get to the feature.xml. (the feature jar really just contains the feature.xml). Open the feature.xml, and it should look like:

<?xml version="1.0" encoding="UTF-8"?>
<feature
  id="org.drools.ide"
  label="Drools Rule Workbench"
  version="1.0.2"> <!-- UPDATE THIS !! -->

   <description>
  JBoss Rules (Drools) Workbench for developers.
   </description>

   <copyright>
  Copyright 2005 JBoss Inc
   </copyright>

   <license>
  Licensed under the Apache License, Version 2.0(the &quot;License&quot;);
 you may not use this file except in compliance with the License.
  You may obtain a copy of the License at
  
   http://www.apache.org/licenses/LICENSE-2.0
  
 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
   </license>

   <plug-in
 id="org.drools.ide"
 download-size="0"
 install-size="0"
 version="1.0.0"/> <!-- THIS JUST HAS TO BE CONSISTENT WITH THE plug-in -->

</feature>

Change the version number in the FEATURE tag to be the same as what you referred to in the site.xml. If you changed the version number of the main plug-in, you will need to put the version number in the plug in tag (which refers to org.drools.ide plug-in). Then zip up the feature.xml into a jar with the same name as you referred to in the site.xml.

Finally, drop the plug-in jar into the /plugins jar directory of the update site (get the actual plug-in from the exported plug-in in the previous step). Now you can upload the site as is, and it will show up as a new version for Eclipse clients.