Chapter 1. Welcome

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.

2.1. What is New and Noteworthy in Drools 5.2.0

2.1.1. Knowledge API (renamed from Drools API)

2.1.1.1. Core

2.1.1.1.1. MVEL

The MVEL dialect has been improved. We have moved all variable
lookups to the new indexed factories, which should allow faster
execution, as well as being simpler code. The build process for mvel
has been reviewed to streamline it to avoid wasteless object creation
so that the build time is faster. We still have some more improvements
on this to share the ParserConfiguration which will make each MVEL
compilation unit faster to initalise and use less memory, as they will
share import information for each package.

It was always possible to execute with MVEL in both dynamic and
strict mode, with strict mode for static type safety the default. This
is configurable via the MVEL dialect configuration:

drools.dialect.mvel.strict = <true|false>

However there were some places in execution when strict mode was
not enforced. Effort has now been done to ensure that type safety is
enforced through out, unless "strict == false". This means that some
bad code that compiled before may not compile now, because it is not
type safe. For those cases where the type safety cannot be achieved at
compile time we added the @typesafe annotation, discussed in it's own
section.

2.1.1.1.2. Classloader

The Classloader has been improved to use a CompositeClassLoader
instead of the previous hierarchical "parent" classloader. This was
necessary for OSGi where each module needs it's own classpath, but
reflection will not work if classloader cannot be found. Modules now
add themselves to the composite classloader when first initialised.
This is also exposed to the user where the previous Classloader
argument on the kbase and kbuilder configuration now takes vararg of
ClassLoaders, all of which are now searchable.

2.1.2. Drools Expert and Fusion

2.1.2.1. Lazy Truth Maintenance

You no longer need to enable or disable truth maintenance, via the
kbase configuration. It is now handled automatically and turned on only
when needed. This was done along with the code changes so that all entry
points use the same code, previous to this the default entry point and
named entry points used different code, to avoid TMS overhead for event
processing.

2.1.2.2. Multi-function Accumulates

The accumulate CE now supports multiple functions. For instance,
if one needs to find the minimum, maximum and average value for the same
set of data, instead of having to repeat the accumulate statement 3
times, a single accumulate can be used.

2.1.2.5. Free Form expressions in Constraints (New Parser)

The parser has been rewritten. We had reached the limitations of
what we could achieve in pure ANTLR and moved to a hybrid parser, that
adds flexibility to the language.

The main benefit with the new parser is that the language now
support free form expressions for constraints and 'from' statements. So
complex expressions on nested accessors, method calls etc should now all
be possible as simple constraints without wrapping them with an
eval(.....). This was also important for us to start to move towards a
single consistent grammer for both the "when" left hand side and "then"
right hand side. As previously we had to document the restricted
limitations of a field constraint on the LHS compared to expressions
used inside of an 'eval' or used on the RHS. Complex expressions are
still internally rewritten as evals, so it's just syntacic sugar.

2.1.2.7. Positional Arguments

Patterns now support positional arguments on type
declarations.

Positional arguments are ones where you don't need to specify the
field name, as the position maps to a known named field. i.e. Person(
name == "mark" ) can be rewritten as Person( "mark"; ). The semicolon
';' is important so that the engine knows that everything before it is a
positional argument. Otherwise we might assume it was a boolean
expression, which is how it could be interpretted after the semicolon.
You can mix positional and named arguments on a pattern by using the
semicolon ';' to separate them. Any variables used in a positional that
have not yet been bound will be bound to the field that maps to that
position.

declare Cheese
name : String
shop : String
price : int
end

The default order is the declared order, but this can be overiden
using @Position

The @Position annotation, in the org.drools.definition.type
package, can be used to annotate original pojos on the classpath.
Currently only fields on classes can be annotated. Inheritence of
classes is supported, but not interfaces of methods yet.

Example patterns, with two constraints and a binding. Remember
semicolon ';' is used to differentiate the positional section from the
named argument section. Variables and literals and expressions using
just literals are supported in posional arguments, but not
variables.

2.1.2.8. Backward Chaining

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 may 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.
If the ? is ommitted the query will be executed as a live "open query"
with reactiveness, similar to how normal patterns work.

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.

Because Drools does not allow multiple bindings on the same
variable we introduce ':=' unification symbol to support this.

As previously mentioned you can use live "open" queries to
reactively receive changes over time from the query results, as the
underlying data it queries against changes. Notice the "look" rule calls
the query without using '?'.

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

It is possible to call queries from java leaving arguments
unspecified using the static field org.drools.runtime.rule.Variable.v -
note you must use 'v' and not an alternative instanceof Variable. The
following example will return all objects contained in the
office.

The algorithm uses stacks to handle recursion, so the method stack
will not blow up.

2.1.2.9. Non Typesafe Classes

@typesafe( <boolean>) has been added to type declarations.
By default all type declarations are compiled with type safety enabled;
@typesafe( false ) provides a means to override this behaviour by
permitting a fall-back, to type unsafe evaluation where all constraints
are generated as MVEL constraints and executed dynamically. This can be
important when dealing with collections that do not have any generics or
mixed type collections.

2.1.2.10. Session Reports

Added experimental framework to inspect a session and generate a
report, either based on a predefined template or with a user created
template.

2.1.3. Drools and jBPM integration

2.1.3.1. Improved Camel integration

Camel integration using the Drools EndPoint was improved with the
creation of both DroolsConsumer and DroolsProducer components.
Configurations were added to support the insertion of either Camel's
Exchange, Message or Body into the Drools session, allowing for the easy
development of dynamic content based routing applications. Also, support
to entry points was added.

2.1.4. Merging Drools Flow into jBPM5

The Drools Flow project and the jBPM project have been merged into
the the newest version of the jBPM project, called jBPM5. jBPM5 combines
the best of both worlds: merging the experience that was built up with the
jBPM project over several years in supporting stable, long-living business
processes together with the improvements that were prototyped as part of
Drools Flow to support more flexible and adaptive processes. Now that jBPM
5.0 has been released, the Drools project will be using jBPM5 as the
engine to support process capabilities. Drools Flow as a subproject will
no longer exist, but its vision will continue as part of the jBPM project,
still allowing (optional but) advanced integration between business rules,
business processes and complex event processing and a unified environment
for all three paradigms.

The impact for the end user however should be minimal, as the
existing (knowledge) API is still supported, the underlying implementation
has just been replaced with a newer version. All existing features should
still be supported, and many more.

2.1.5. Guvnor

2.1.5.1. Guvnor Look & Feel Moving Closer To Native GWT Look

We have removed GWT-Ext from Guvnor and now only use GWT.

2.1.5.2. Embed Guvnor Editors

Embed Guvnor Editor's in external applications. You can create or
edit assets like Business Rules, Technical Rules, DSL definitions and
Decision Tables in your applications using Guvnor's specific editors.
You can even edit multiple assets at once.

2.1.5.3. Annotations come to Declarative Models

The ability to add annotations in Guvnor to declarative models has
been added. This allows Fact Types to be defined as events.

Figure 2.1. Annotations

Figure 2.2. Annotation editor

2.1.5.4. Support for Complex Event Processing in the guided
editors

The guided editors have been enhanced to allow full use of Drools
Fusion's Complex Event Processing operators, sliding windows and
entry-points.

Figure 2.3. Complex Event Processing

2.1.5.5. Decision Tables

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.

Figure 2.4. Basic Decision Table

2.1.5.5.1. Cell Merging

Adjacent cells in the same column with the same value can be
merged thus eliminating the need for otherwise cluttered views of
multiple rows containing the same value.

Figure 2.5. Merged Decision Table

2.1.5.5.2. Typed-columns

The major basic data-types (numeric, date, text and Boolean) are
handled as such and respond as you'd expect to sorting.

Figure 2.6. Datatype Sorting

2.1.5.5.3. Improved header

The table header section has been improved to show more verbose
information to facilitate design-time understanding. The table has a
fixed header that remains as you'd expect, at the top of the table,
whilst scrolling larger decision tables.

2.1.5.5.4. Tighter integration

2.1.5.5.5. Negation of Fact patterns

Fact Patterns in condition columns can be negated to match when
the defined pattern does not exist in WorkingMemory. In essence it is
now possible to construct rules within the decision table equivalent
to the following DRL fragment:-

2.1.5.5.7. Support for "otherwise"

Condition columns containing literal values that use the
equality (==, equal to) or inequality (!=, not equal to) operators can
now contain a meta-value for "otherwise" which represents all other
values not explicitly defined in the column. This feature gives rise
to DRL fragments such as the following:-

We added a new task in drools-ant which helps with configuring
multiple Guvnor instances to be able to share their Jackrabbit
content.

2.1.5.5.11. Configuring Guvnor to use an external RDBMS made easier

The default Guvnor repository configuration uses embedded Derby
databases which writes the workspace and version information to the
local file system. This is not always optimal for a production system
where it makes sense to use an external RDBMS.

We added a new section under the "Administration" tab called
"Repository Configuration" which helps generate the repository.xml
configuration file for a number of databases (Microsoft SQL Server,
MySQL, Oracle, PostgreSQL, Derby, H2)

2.1.5.5.12. Web-based BPMN2 authoring in Guvnor

We have completed big parts of the integration between Guvnor
and the Oryx web-based business process editor. Our primary use cases
supported by this integration are:

- Viewing existing jBPM5 processes in Guvnor

- Prototyping new jBPM5 processes in Guvnor.

Please note that we are still working on full round-tripping
support between the web-based Oryx editor and our BPMN2 support
provided through the eclipse plugin

2.1.6. Eclipse

2.1.6.1. Removal of BRL Guided Editor

The BRL Guided Editor has been removed due to lack of interest and
it falling behind. Its removal allows more focus on the GWT based Guided
Editor in Guvnor. The DRL, text-based, Guided Editor remains
unaffected.

2.1.7. Maven artifactId changes

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 groupId

Old artifactId

New groupId

New artifactId

org.drools

drools (the parent pom)

org.drools

droolsjbpm-parent

org.drools

drools-api

org.drools

knowledge-api

org.drools

drools-docs-introduction

org.drools

droolsjbpm-introduction-docs

org.drools

drools-examples-drl

org.drools

drools-examples

org.drools

drools-examples-fusion / drools-examples-drl (jBPM using
parts)

org.drools

droolsjbpm-integration-examples

org.drools

drools-docs-expert

org.drools

droolsjbpm-expert-docs

org.drools

drools-docs-fusion

org.drools

droolsjbpm-fusion-docs

org.drools

drools-repository

org.drools

guvnor-repository

org.drools

drools-ide-common

org.drools

droolsjbpm-ide-common

org.drools

drools-guvnor

org.drools

guvnor-webapp

org.jboss.drools.guvnor.tools

guvnor-importer

org.drools

guvnor-bulk-importer

org.drools

drools-docs-guvnor

org.drools

guvnor-docs

org.drools

drools-server

org.drools

drools-camel-server

org.drools

drools-docs-integration

org.drools

droolsjbpm-integration-docs

org.drools

drools-flow-core

org.jbpm

jbpm-flow

org.drools

drools-flow-compiler

org.jbpm

jbpm-flow-builder

org.drools

drools-bpmn2

org.jbpm

jbpm-bpmn2

org.drools

drools-flow-persistence-jpa

org.jbpm

jbpm-persistence-jpa

org.drools

drools-bam

org.jbpm

jbpm-bam

org.drools

drools-process-task

org.jbpm

jbpm-human-task

org.drools

drools-gwt-console

org.jbpm

jbpm-gwt-console

org.drools

drools-gwt-form

org.jbpm

jbpm-gwt-form

org.drools

drools-gwt-graph

org.jbpm

jbpm-gwt-graph

org.drools

drools-gwt-war

org.jbpm

jbpm-gwt-war

org.drools

drools-gwt-server-war

org.jbpm

jbpm-gwt-server-war

org.drools

drools-workitems

org.jbpm

jbpm-workitems

org.drools

drools-docs-flow

org.jbpm

jbpm-docs

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

2.2. What is New and Noteworthy in Drools 5.1.0

2.2.1. Drools API

As in Drools 5.0 it is still possible to configure a KnowledgeBase
using configuration, via a xml change set, instead of programmatically. However the change-set namespace
is now versioned. This means that for Drools 5.1, the 1.0.0 xsd should be referenced.

2.2.2. Core

2.2.2.1. JMX Monitoring

JMX monitoring was added to support KnowledgeBase monitoring. This
is specially importand for long running processes like the ones usually
required for event processing. Initial integration with JOPR was also
added. JMX can be inabled with using the properties setting the
knowledge base:

drools.mbeans = <enabled|disabled>

or this option at runtime

kbaseConf.setOption( MBeansOption.ENABLED )

2.2.2.2. Spring

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"

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.

2.2.2.3. Camel

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.

2.2.2.4. Drools Server

Spring, Camel and CXF can be combined for declarative services,
drools-server is a .war that combines these with some sample xml that
works out of the box to get you started, acting like a sort of template.
If you are using the war in JBoss container you'll need to add this
component, http://camel.apache.org/camel-jboss.html. The war includes a
test.jsp showing an echo like example to get you started. This example
just executes a simple "echo" type application. It sends a message to
the rule server that pre-appends the word "echo" to the front and sends
it back. By default the message is "Hello World", different messages can
be passed using the url parameter msg - test.jsp?msg="My Custom
Message".

2.2.2.5. Knowledge Agent Incremental Change Support

The new version of the Knowledge Agent supports newInstance =
false in its configuration (incremental change-set build).

When setting this property to false, the KnowledgeAgent uses the
exisitng KnowledgeBase references apply the incremental changes. Now
KnowledgeAgent's can process monitored resource modifications in an
incremental way. Modified definitions are compiled and compared against
the original version. According to definition's type, the behaves in
different ways:

Rules: For rules, the Agent searches for modifications in its
attributes, LHS and RHS.

Queries: queries are always replaced on kbase wether they are
modified or not.

Other definitions: All other definitions are always replaced
in kbase (like if they were modified). We expect to add better
support for definition's modification detection in further
versions.

The current implementation only supports the deletion of rules,
querries and functions definitions. Type declarations cannot be
deleted.

2.2.2.6. Session Inspection and Reporting framework

A new API based framework for runtime session inspection and
reporting was introduced, allowing for better data gathering during
debugging or profiling of the application. This inspection framework
will become the basis of the tooling features to help providing more
detailed information about the contents of each session. This api is
experimental and not in drools-api for now, but feel free to play and
help us improve it.

The StatefulKnowledgeSessionInfo instance will contain a lot of
relevant data gathered during the analysis of the session. A simple
example report template is provided and can be generated with the
following API call:

Example 2.11. Generating a Report

String report =SessionReporter.generateReport("simple", info,null);

2.2.3. Expert

2.2.3.1. Differential Update

Rete traditional does an update as a retract + assert, for a given
fact this causes all partial matches to be destroyed, however during the
assert some of which will be recreated again; because they were true
before the update and still true after the update. This causes a lot of
uneccessary object destruction and creation which puts more load on the
Garbage Collector. Now an update is a single pass and inspects the
partial matches in place avoiding the unecessary destruction of partial
matches. It also removes the need to under go a normalisation process
for events and truth maintenance; the normalisation process was where we
would look at the activations retracted and activations inserted to
figure out what was truly added and what was truly inserted to determine
the "diff".

2.2.3.2. Channels

Exit Points have been replaced by the more aptly named channels,
we felt this was more appropriate as they may be used by more than juse
the rule engine and not an exact oppposte if Entry Points. Where entry
points are explicitey related to entering a partition in the Rete
network.

2.2.3.3. Live Querries

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.

2.2.4. Flow

2.2.4.1. BPMN2

As we already announced earlier, the Drools team has decided to
support the use of the upcoming BPMN 2.0 specification for specifying
business processes using XML. This milestone includes a significant
extension of the BPMN2 parser to support more of the BPMN2 features
using Drools Flow. More specifically:

more extensive event support: much more combinations of event
types (start, intermediate and end) and event triggers (including
for example error, escalation, timer, conditional and signal
events), have been included, as well as (interrupting and
non-interrupting) boundary events

sub-process parameters

diverging inclusive gateway

etc.

BPMN2 processes have also been integrated in the entire Drools
tool chain, to support the entire life cycle of the business process.
This includes

The ability to use BPMN2 processes in combination with our
Eclipse tooling

Guvnor as process repository

web-based management using the BPM console

auditing and debugging

domain-specific processes

etc.

As a result, Drools Flow is not only the first open-source process
engine that supports such a significant set of BPMN2 constructs
natively, our knowledge-oriented approach also allows you to easily
combine your BPMN2 processes with business rules and complex event
processing, all using the same APIs and tools.

2.2.4.2. Web-based Management console

Drools Flow processes can now also be managed through a web
console. This includes features like managing your process instances
(starting/stopping/inspecting), inspecting your (human) task list and
executing those tasks, and generating reports.

This console is actually the (excellent!) work of Heiko Braun, who
has created a generic BPM console that can be used to support multiple
process languages. We have therefore implemented the necessary
components to allow this console to communicate with the Drools Flow
engine.

2.2.4.3. Pluggable Variable Persistence

Drools Flow can persist the runtime state of the running processes
to a database (so they don't all need to be in memory and can be
restored in case of failure). Our default persistence mechanism stores
all the runtime information related to one process instance as a binary
object (with associated metadata). The data associated with this process
instance (aka process instance variables) were also stored as part of
that binary object. This however could generate problem (1) when the
data was not Serializable, (2) when the objects were too large to
persist as part of the process instance state or (3) when they were
already persisted elsewhere. We have therefor implemented pluggable
variable persisters where the user can define how variable values are
stored. This for example allows you to store variable values separately,
and does support JPA entities to be stored separately and referenced
(avoiding duplication of state).

2.2.4.4. Improved Process Instance Migration

Over time, processes may evolve. Whenever a process is updated, it
is important to determine what should happen to the already running
process instances. We have improved our support for migrating running
process instances to a newer version of the process definition. Check
out the Drools Flow documentation for more information.

2.2.4.5. Installation Script

The Drools build now exports an installer that simplifies
installing the Eclipse plugin, Guvnor and the gwt-console. It creates
and copies the necessary jars and wars and deploys them to the JBoss AS.
It also includes a simple evaluation process example you can use to test
your setup. For more info, download the drools installer and take a look
at the readme within.

2.2.5. Guvnor

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.

2.2.5.1. Discussions

The comments are below the "documentation" section (and of course
optional) (and there is an Atom feed to them).

Figure 2.12. Realtime Discussions

A "backchannel" type connection that is kept open from the browser
to allow messages to push back - this means (when enabled) that messages
show up in real time (and other handy things like if something is added
to a list - the list is updated).

Clicking on the recently opened item will open a listing
of all items you have "recently" opened (it tracks a few hundred
items that you were last to look at).

Recently Edited

Any items that you save changes to, or comment on will
show up here, once again.

Incoming changes

This tracks changes made by *other people* to items that
are in *your* "Recently Edited" list. When you open these items
they then are removed from this list (but remain in your
Recently Edited list).

Figure 2.14. Inbox Item Lists

2.2.5.3. Bulk Importer

The Guvnor-Importer is a maven build tool that recurses your rules
directory structure and constructs an xml import file that can be
manually imported into the Drools-Guvnor web interface via the
import/export administration feature.

2.2.5.4. DroolsDoc

PDF document containing information about the package and each DRL
asset. DroolsDoc for knowledge package can be downloaded from package
view under "Information and important URLs"

2.2.5.5. Update to GWT 2.0

GWT was updated, making Guvnor faster.

2.2.5.6. Build in Selector

The built in selector allows user to choose what assets to build
according to:

Status (eg, Dev, QA etc)

Category

Metadata

2.2.5.7. Single Asset Verification

It is possible to verify just the asset you are working on (
ruleflow, rule, decision table ). Verification finds issues like
conflicting restrictions in a rule or redundant rows in decision
tables.

2.2.5.8. Global Area

Assets stored in Global area can be shared to all packages.

2.2.5.9. Diff Check between Snapshots

Lists the changes between two snapshots.

2.2.5.10. View Multiple Assets in One Tab

Makes it possible to open more than one asset into one view. All
the assets can be saved and edited as a group.

2.2.5.11. From/Collect/Accumulate support

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.

Figure 2.15. From CE 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

Figure 2.16. From Collect CE Builder

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

Figure 2.17. From Accumulate CE Builder

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.

2.2.5.12. Rule Templates

Rule Templates allow the Guided editor to be used to build complex
rules that can then be authored easily through a spreadsheet's tabular
data metaphor. Instead of a field's value, simply mark it as a named
"Template Key" and that key is available as a column in the grid. Each
row will be applied to the rule template to generate a rule.

Figure 2.18. Adding a Template Key in the 'WHEN' Section

Figure 2.19. Adding a Template Key in the "THEN" Section

Figure 2.20. Populating Rows against those Template Keys

Figure 2.21. Each Row generates a Rule

2.2.5.13. Working Sets

When modelling rules the user gets exposed to all the fact types
which can be a bit over whelming. Working Sets allow related fact types
can be grouped together, provided a more managable view of selecting
fact types, when authoring rules

Figure 2.22. Show the imported types

Figure 2.23. Create Animals Working Set

Figure 2.24. Without the Working Set all types are visible

Figure 2.25. Select the Animals Working Set

Figure 2.26. The available types are reduced

2.2.5.14. Fact Constraints

Working Sets can be combined with fact consraints to provide
additional design time validation. For instance if you are authoring a
rule on someone's age, we can know the valid ranges at design time and
use this to constrain the author. The fact constraints are part of the
workingset and when authoring a rule you must select the work set
constraints that you wish to be applied as part of the validation
process.

Figure 2.27. Selecting the field

Figure 2.28. Selectng the type of field constraint

Figure 2.29. A example range constraint

Figure 2.30. Select the working set to validate the age field

Figure 2.31. A age of 5 is invalid

2.2.5.15. Guided Rule Editor

Editing rules is made more explicit. Editor is less "boxy" and
rules are written more as a normal text. "contains" keyword was added
and binding variables to restrictions is now easier.

2.2.5.15.1. Pattern Order

Guided Editor supports Pattern reordering in LHS and RHS
sections, as well as positional inserting, new Patterns can be
inserted in any order (and not always at the end).

Figure 2.32. Move elements up or down

Figure 2.33. Insert Element at any position

2.2.5.16. Decision Table (Guvnor)

Keyword "in" was added.

Columns can be moved and location of a new row can be selected
freely.

2.2.6. Eclipse

2.2.6.1. Group Rules in outline view

You can now use sorting and grouping for Agenda Groups.

Figure 2.34. Group by Agenda Group

Figure 2.35. Sort by Agenda Group

2.2.6.2. Drag/Drop File support in audit View

It is now possible to drag and drop log files into the audit
view.

2.2.7. Known Issues

2.2.7.1. Multithread mode

There is a known issue with the experimental multi-thread
execution mode as described in the following JIRA.

2.3. What is New and Noteworthy in Drools 5.0.0

2.3.1. Drools API

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:

org.drools.builder.KnowledgeBuilder

org.drools.KnowledgeBase

org.drools.agent.KnowledgeAgent

org.drools.runtime.StatefulKnowledgeSession

org.drools.runtime.StatelessKnowledgeSession

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:

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.

Example 2.25. These services currently are not started by default, to start
them do the following

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.

This works with the new "declare" statement - you can now
declare types in drl itself. You can then populate these without using
a pojo (if you like). These types are then available in the
rulebase.

Fine grained security (lock down access to the app per package
or per category). Users who only have category permissions have
limited UI capability (ideal for business users)

Execution server - access rules via XML or JSON for
execution

Category rules allows you to set 'parent rules' for a category.
Any rules appearing in the given category will 'extend' the rule
specified - ie inherit the conditions/LHS. The base rule for the
category can be set on package configuration tab. RHS is not
inherited, only the LHS

Scenario runner detects infinite loops

Scenario runner can show event trace that was recorded by audit
logger

DSL sentences in guided editor can now be set to show enums as a
dropdown, dates as a date picker, booleans as a checkbox and use
regular expressions to validate the inputs (DSL Widgets in
Guvnor)

Functions can be edited with text editor

It is possible to add objects to global collections.

Translations to English, Spanish, Chinese and Japanese

2.3.3. Drools Expert

2.3.3.1. Asymmetrical Rete algorithm implementation

Shadow proxies are no longer needed. Shadow proxies protected the
engine from information change on facts, which if occurred outside of
the engine's control it could not be modified or retracted.

2.3.3.2. PackageBuilder can now build multiple
namespaces

You no longer need to confine one PackageBuilder to
one package namespace. Just keeping adding your DRLs for any namespace
and getPackages() returns an array of Packages for each of
the used namespaces.

Example 2.26. Getting multiple packages

Package[] packages = pkgBuilder.getPackages();

2.3.3.3. RuleBase attachment to
PackageBuilder

It is now possible to attach a RuleBase to a
PackageBuilder, this means that rules are built and added
to the rulebase at the same time. PackageBuilder uses the
Package instances of the actual RuleBase as
it's source, removing the need for additional Package
creation and merging that happens in the existing approach.

2.3.3.4. Binary marshalling of stateful sessions

Stateful sessions can now saved and resumed at a later date.
Pre-loaded data sessions can now be created. Pluggable strategies can be
used for user object persistence, i.e. hibernate or identity
maps.

2.3.3.5. Type Declaration

Drools now supports a new base construct called Type Declaration.
This construct fulfils two purposes: the ability to declare fact
metadata, and the ability to dynamically generate new fact types local
to the rule engine. The Guvnor modelling tool uses this underneath. One
example of the construct is:

2.3.3.6. Declaring Fact Metadata

To declare and associate fact metadata, just use the @ symbol for
each metadata ID you want to declare. Example:

Example 2.29. Declaring metadata

declare StockTick
@role( event )
end

2.3.3.7. Triggering Bean Generation

To activate the dynamic bean generation, just add fields and types
to your type declaration:

Example 2.30. Declaring Person

declare Person
name : String
age : int
end

2.3.3.8. DSL improvements

A series of DSL improvements were implemented, including a
completely new parser and the ability to declare matching masks for
matching variables. For instance, one can constrain a phone number field
to a 2-digit country code + 3-digit area code + 8-digit phone number,
all connected by a "-" (dash), by declaring the DSL map like: The phone
number is {number:\d{2}-\d{3}-\d{8}} Any valid java regexp may be used
in the variable mask.

2.3.3.9. fireUntilHalt()

Drools now supports "fireUntilHalt()" feature, that starts the
engine in a reactive mode, where rules will be continually fired, until
a halt() call is made. This is specially useful for CEP scenarios that
require what is commonly known as "active queries".

2.3.3.10. Rule Base partitioning and multi-thread propagation

Drools ReteOO algorithm now supports an option to start the rule
base in a multi-thread mode, where Drools ReteOO network is split into
multiple partitions and rules are then evaluated concurrently by
multiple threads. This is also a requirement for CEP where there usually
are several independent rules running concurrently, with near realtime
performance/throughput requirements and the evaluation of one can not
interfere with the evaluation of others.

2.3.3.11. XSD Model Support

Drools now supports XSD models. Remember though the XSD model is
generated as pojos local to the Drools classloader. A helper class is
there to assist in the creation of the model in the packagebuilder. Once
the data model is generated you'll typically use the JAXB dataloader to
insert data.

2.3.3.12. Data Loaders

Drools now supports two data loaders, Smooks and JAXB. Smooks is
an open source data transformation tool for ETL and JAXB a standard sun
data mapping tool. Unit tests showing Smooks can be found here and JAXB
here.

2.3.3.13. Type safe configuration

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:

Example 2.32. Configuring alpha threshold

config.setOption(AlphaThresholdOption.get(5));

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

2.3.3.14. New accumulate functions: collectSet and collectList

There are times when it is necessary to collect sets or lists of
values that are derived from the facts attributes, but are not facts
themselves. In such cases, it was not possible to use the collect CE.
So, Drools now has two accumulate functions for such cases: collectSet
for collecting sets of values (i.e., with no duplicate values) and
collectList for collecting lists of values (i.e., allowing duplicate
values):

2.3.3.15. New metadata for type declarations:
@propertyChangeSupport

Facts that implement support for property changes as defined in
the Javabean(tm) spec, now can be annotated so that the engine register
itself to listen for changes on fact properties. The boolean parameter
that was used in the insert() method in the Drools 4 API is deprecated
and does not exist in the drools-api module.

Example 2.34. @propertyChangeSupport

declare Person
@propertyChangeSupport
end

2.3.3.16. Batch Executor

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:

Example 2.35. Using CommandFactory

ksession.execute(CommandFactory.newInsert( person ));

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.

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:

2.3.3.18. Knowledge Agent

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 ResourceChangeScannerServiceif 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 60sResourceFactory.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 scanningaconf.setProperty("drools.agent.newInstance","true");// resource changes results in a new instance of the KnowledgeBase being built,//this cannot currently be set to falsefor incremental buildingKnowledgeAgent 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.

2.3.4. Drools Flow

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.

2.3.4.1. Process Instance view at a specific breakpoint

Figure 2.42. Rule Flow properties

Figure 2.43. Current active nodes in a workflow in a specific
breakpoint

2.3.4.2. New Nodes

Timers:

A timer node can be added which causes the execution of the node
to wait for a specific period. Currently just uses JDK defaults of
initial delay and repeat delay, more complex timers will be available in
further milestones.

Human Task:

Processes can include tasks that need to be executed by human
actors. Human tasks include parameters like taskname, priority,
description, actorId, etc. The process engine can easily be integrated
with existing human task component (like for example a WS-HumanTask
implementation) using our pluggable work items (see below). Swimlanes
and assignment rules are also supported.

The palette in the screenshot shows the two new components, and
the workflow itself shows the human task in use. It also shows two "work
items" which is explained in the next section:

Figure 2.44. Human task

2.3.4.3. Domain Specific Work Items

Domain Specific Work Items are pluggable nodes that users create
to facilitate custom task execution. They provide an api to specify a
new icon in the palette and gui editor for the tasks properties, if no
editor gui is supplied then it defaults to a text based key value pair
form. The api then allows execution behaviour for these work items to be
specified. By default the Email and Log work items are provided. The
Drools flow Manual has been updated on how to implement these.

The below image shows three different work items in use in a
workflow, "Blood Pressure", "BP Medication", "Notify GP":

Figure 2.45. Work items

This one ows a new "Notification" work item:

Figure 2.46. Notification

2.3.4.4. Extensible Process Definition Language (ePDL)

Drools 4.0 used Xstream to store it's content, which was not
easily human writeable. Drools 5.0 introduced the ePDL which is a XML
specific to our process language, it also allows for domain specific
extensions which has been talked about in detail in this blog posting
"Drools Extensible Process Definition Language (ePDL) and the Semantic
Module Framework (SMF)". An example of the XML language, with a DSL
extension in red, is shown below.

2.3.4.5. Pluggable Nodes

The underlying nodes for the framework are completely pluggable
making it simple to extend and to implement other execution models. We
already have a partial implementation for OSWorkflow and are working
with Deigo to complete this to provide a migration path for OSWorkflow
users. Other enhancements include exception scopes, the ability to
include on-entry and on-exit actions on various node types, integration
with our binary persistence mechanism to persist the state of long
running processes, etc. Check out the Drools Flow documentation to learn
more.

2.3.4.6. Human tasks

Human task management is very important in the context of
processes. While we allow users to plug in any task component they
prefer, we have developed a human task management component that
supports the entire life cycle of human tasks based on the WS-HumanTask
specification.

2.3.4.7. New functions to the Drools Flow language

Event nodes that allow a process to respond to external
events

Exception handlers and exception handler scopes to handle
exceptions that could be thrown

A ForEach node allows instantiating a section of your flow
multiple times, for each element in a collection

Data type support has been extended

Timers are integrated with common node types

As a result, new node types and properties have been
added to the Drools Flow editor in Eclipse. You can also find examples
of these new features in the integration tests (e.g.
ProcessExceptionHandlerTest, ProcessTimerTest, etc.).

2.3.4.8. Work items

Our pluggable work item approach allows you to plug in
domain-specific work in your process in a declarative manner. We plan to
build a library of common work items and already provide an
implementation for sending emails, finding files, archiving, executing
system commands, logging and human tasks.

2.3.4.9. JPA

Improved support for persistence (JPA) and transactions (JTA).

Example 2.45. An example on how to use persistence and transactions in
combination with processes

// create a new JPA-based session and specify the JPA entity manager factoryEnvironment env =KnowledgeBaseFactory.newEnvironment();env.set(EnvironmentName.ENTITY_MANAGER_FACTORY,Persistence.createEntityManagerFactory("emf-name"));env.set(EnvironmentName.TRANSACTION_MANAGER,TransactionManagerServices.getTransactionManager());StatefulKnowledgeSession ksession =JPAKnowledgeService.newStatefulKnowledgeSession( kbase,null, env );//KnowledgeSessionConfiguration may be null, and a default will be usedint sessionId = ksession.getId();//if no transaction boundary is specified, the method invocation is executed in a new transaction automaticallyProcessInstance processInstance = ksession.startProcess("org.drools.test.TestProcess");// the users can also specify the transaction boundary themselvesUserTransaction ut =(UserTransaction)newInitialContext().lookup("java:comp/UserTransaction");ut.begin();ksession.insert(newPerson("John Doe"));ksession.startProcess("org.drools.test.TestProcess");ksession.fireAllRules();ut.commit();

2.3.4.10. Variable Injection

Support direct access to process variables in both MVEL and Java
in code constraints and actions, so if you have a variable called
"person" in your process, you can now describe constraints like:

2.3.4.11. Miscellaneous Enhancements

Process instances can now listen for external events by
marking the event node property "external" as true. External
events are signaled to the engine using
session.signalEvent(type, eventData) More information
on how to use events inside your processes can be found in the
Drools Flow documentation here:
https://hudson.jboss.org/hudson/job/drools/lastSuccessfulBuild/artifact/trunk/target/docs/drools-flow/html/ch03.html#d0e917

Process instances are now safe for multi-threading (as
multiple thread are blocked from working on the same process
instance)

Process persistence / transaction support has been further
improved. Check out the drools-process/drools-process-enterprise
project for more information.

The human task component has been extended to support all
kinds of data for input / output / exceptions during task
execution.

Example 2.47. As a result, the life cycle methods of the task client
have been extended to allow content data

It is now possible to migrate old Drools4 RuleFlows (using
the xstream format) to Drools5 processes (using readable xml)
during compilation. Migration will automatically be performed when
adding the RuleFlow to the KnowledgeBase when the following system
property is set: drools.ruleflow.port = true

The "Transform" work item allows you to easily transform
data from one format to another inside processes. The code and an
example can be found in the drools-process/drools-workitems
directory.

Function imports are now also supported inside
processes.

The history log - that keeps the history of all executed
process instances in a database - has been extended so it is now
capable of storing more detailed information for one specific
process instance. It is now possible to find out exactly which
nodes were triggered during the execution of the process
instance.

A new type of join has been added, one that will wait until
n of its m incoming connections have been completed. This n could
either be hardcoded in the process or based on the value of a
variable in the process.

Improvements have been made to make persistence easier to
configure. The persistence approach is based on a command service
that makes sure that all the client invocations are executed
inside a transaction and that the state is stored in the database
after successful execution of the command. While this was already
possible in M4 using the commands directly, we have extended this
so that people can simply use the normal StatefulKnowledgeSession
interface but simply can configure the persistence using
configuration files. For more details, check out the chapter on
persistence in the Drools Flow documentation.

2.3.5. Drools Fusion

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.

2.3.5.1. Event Semantics

Events are (from a rules engine perspective) a special type of
fact that has a few special characteristics:

they are immutable

they have strong time-related relationships

they may have clear lifecycle windows

they may be transparently garbage collected after it's
lifecycle window expires

they may be time-constrained

they may be included in sliding windows for reasoning

2.3.5.2. Event Declaration

Any fact type can assume an event role, and its corresponding
event semantics, by simply declaring the metadata for it.

Example 2.48. Both existing and generated beans support event
semantics:

2.3.5.3. Entry-Point Stream Listeners

A new key "from entry-point" has been added to allow a pattern in
a rule to listen on a stream, which avoids the overhead of having to
insert the object into the working memory where it is potentially
reasoned over by all rules.

2.3.5.4. Event Correlation and New Operators

Event correlation and time based constraint support are
requirements of event processing, and are completely supported by Drools
5.0. The new, out of the box, time constraint operators can be seen in
these test case rules: test_CEP_TimeRelationalOperators.drl

As seen in the test above, Drools supports both: primitive events,
that are point in time occurrences with no duration, and compound
events, that are events with distinct start and end timestamps.

The complete list of operators are:

coincides

before

after

meets

metby

overlaps

overlappedby

during

includes

starts

startedby

finishes

finishedby

2.3.5.5. Sliding Time Windows

Drools 5.0 adds support for reasoning over sliding windows of
events. For instance:

StockTick( symbol == "RHAT" ) over window:time( 60 )

The above example will only pattern match the RHAT stock ticks
that happened in the last 60 clock ticks, discarding any event older
than that.

2.3.5.6. Session Clock

Enabling full event processing capabilities requires the ability
to configure and interact with a session clock. Drools adds support for
time reasoning and session clock configuration, allowing it to not only
run real time event processing but also simulations, what-if scenarios
and post-processing audit by replaying a scenario.

Example 2.50. The Clock is specified as part of the SessionConfiguration, a
new class that is optionally specified at session creation
time

2.3.5.7. Event Garbage Collection

Since events usually have strong temporal relationships, it is
possible to infer a logical time window when events can possibly match.
The engine uses that capability to calculate when an event is no longer
capable of matching any rule anymore and automatically retracts that
event.

2.3.5.8. Time Units Support

Drools adopted a simplified syntax for time units, based on the
ISO 8601 syntax for durations. This allows users to easily add temporal
constraints to the rules writing time in well known units.
Example:

SomeEvent( this after[1m,1h30m] $anotherEvent
)

The above pattern will match if SomeEvent happens between 1 minute
(1m) and 1 hour and 30 minutes after $anotherEvent.

2.3.5.9. Support to event expiration policy

added the ability to define a per-type event expiration policy. In
the example below, the StockTick events will expire 10 minutes after
they enter the system:

declare StockTick @role( event ) @expires( 10m ) end

2.3.5.10. Support to temporal operations over arbitrary dates.

Example 2.51. added the ability for point-in-time operators (before, after
and coincides) to be used with any arbitrary date field

rule "Allow access"
when
WorkHours( $s : start, $e : end )
LogIn( time after $s, time before $e )
then
// allow access
end

2.3.6. Eclipse IDE

Support multiple runtimes: The IDE now supports multiple
runtimes. 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 either point the IDE to the release of your
choice, or you can simply create a new runtime on your file system
from the jars included in the Drools Eclipse plugin. Drools runtimes
can be configured by opening up the Eclipse preferences and selecting
the Drools -> Installed Drools Runtimes category, as shown below.

Figure 2.47. Run times

Debugging of rules using the MVEL dialect has been fixed

Drools Flow Editor

Process Skins allow you to define how the different
RuleFlow nodes are visualized. We now support two skins: the
default one which existed before and a BPMN skin that visualizes
the nodes using a BPMN-like representation:
http://blog.athico.com/2008/10/drools-flow-and-bpmn.html

An (X)OR split now shows the name of the constraint as the
connection label

Custom work item editors now signal the process correctly
that it has been changed

2.4. What is new in Drools 4.0

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.

2.4.1. Language Expressiveness Enhancements

New Conditional Elements: from, collect, accumulate and
forall

New Field Constraint operators: not matches, not contains, in,
not in, memberOf, not memberOf

New Implicit Self Reference field: this

Full support for Conditional Elements nesting, for First Order
Logic completeness.

Support for multi-restrictions and constraint connectives
&& and ||

Parser improvements to remove previous language limitations,
like character escaping and keyword conflicts

Support for pluggable dialects and full support for MVEL
scripting language

2.4.5. Miscellaneous Enhancements

Slimmed down dependencies and smaller memory footprint

2.5. Upgrade tips from Drools 3.0.x to Drools 4.0.x

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.

2.5.1. API changes

There are a few API changes that are visible to regular users and
need to be fixed.

2.5.1.1. Working Memory creation

Drools 3.0.x had only one working memory type that worked like a
stateful working memory. Drools 4.0.x introduces separate APIs for
Stateful and Stateless working memories that are called now Rule
Sessions. In Drools 3.0.x, the code to create a working memory
was:

Example 2.52. Drools 3.0.x: Working Memory Creation

WorkingMemory wm = rulebase.newWorkingMemory();

In Drools 4.0.x it must be changed to:

Example 2.53. Drools 4.0.x: Stateful Rule Session Creation

StatefulSession wm = rulebase.newStatefulSession();

The StatefulSession object has the same behavior as the
Drools 3.0.x WorkingMemory (it even extends the WorkingMemory
interface), so there should be no other problems with this fix.

2.5.1.2. Working Memory Actions

Drools 4.0.x now supports pluggable dialects and has built-in
support for Java and MVEL scripting language. In order to avoid keyword
conflicts, the working memory actions were renamed as showed
below:

Table 2.2. Working Memory Actions equivalent API methods

Drools 3.0.x

Drools 4.0.x

WorkingMemory.assertObject()

WorkingMemory.insert()

WorkingMemory.assertLogicalObject()

WorkingMemory.insertLogical()

WorkingMemory.modifyObject()

WorkingMemory.update()

2.5.2. Rule Language Changes

The DRL Rule Language also has some backward incompatible changes as
detailed below.

2.5.2.1. Working Memory Actions

The Working Memory actions in rule consequences were also changed
in a similar way to the change made in the API. The following table
summarizes the change:

Table 2.3. Working Memory Actions equivalent DRL commands

Drools 3.0.x

Drools 4.0.x

assert()

insert()

assertLogical()

insertLogical()

modify()

update()

2.5.2.2. Primitive support and unboxing

Drools 3.0.x did not had native support for primitive types and
consequently, it auto-boxed all primitives in it's respective wrapper
classes. That way, any use of a boxed variable binding required a manual
unbox.

Drools 4.0.x has full support for primitive types and does not
wrap values anymore. So, all previous unwrap method calls must be
removed from the DRL.

2.5.3. Drools Update Tool

The Drools Update tools is a simple program to help with the upgrade
of DRL files from Drools 3.0.x to Drools 4.0.x.

At this point, its main objective is to upgrade the memory action
calls from 3.0.x to 4.0.x, but expect it to grow over the next few weeks
covering additional scenarios. It is important to note that it does not
make a dumb text search and replace in rules file, but it actually parses
the rules file and try to make sure it is not doing anything unexpected,
and as so, it is a safe tool to use for upgrade large sets of rule
files.

The Drools update tool can be found as a maven project in the
following source repository
http://anonsvn.labs.jboss.com/labs/jbossrules/trunk/experimental/drools-update/
you just need to check it out, and execute the maven clean install action
with the project's pom.xml file. After resolve all the class path
dependencies you are able to run the toll with the following
command:

-f pattern for the files to be updated. The format is the same
as used by ANT: * = single file, directory ** = any level of
subdirectories EXAMPLE: src/main/resources/**/*.drl = matches all
DRL files inside any subdirectory of /src/main/resources

-s,--sufix the sufix to be added to all updated files

2.5.4. DSL Grammars in Drools 4.0

It is important to note that the DSL template engine was rewritten
from scratch to improve flexibility. One of the new features of DSL
grammars is the support to Regular Expressions. This way, now you can
write your mappings using regexp to have additional flexibility, as
explained in the DSL chapter. Although, now you have to escape characters
with regexp meaning. Example: if previously you had a matching
like:

Example 2.56. Drools 3.0.x mapping

[when][]- the {attr} is in [ {values} ]={attr} in ( {values} )

Now, you need to escape '[' and ']' characters, as they have special
meaning in regexps. So, the same mapping in Drools 4.0 would be:

Example 2.57. Drools 4.0.x mapping with escaped characters

[when][]- the {attr} is in \[ {values} \]={attr} in ( {values} )

2.5.5. Rule flow Update for 4.0.2

The Rule flow feature was updated for 4.0.2, and now all your ruleflows must declare a package name.

3.1. Installing and using

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.

3.1.1. Dependencies and jars

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

knowledge-api.jar - this provides the interfaces and factories. It also helps clearly show what is
intended as a user api and what is just an engine api.

drools-core.jar - this is the core engine, runtime component. Contains both the RETE engine and the LEAPS
engine. This is the only runtime dependency if you are pre-compiling rules (and deploying via Package or
RuleBase objects).

drools-compiler.jar - this contains the compiler/builder components to take rule source, and build
executable rule bases. This is often a runtime dependency of your application, but it need not be if you are
pre-compiling your rules. This depends on drools-core

drools-jsr94.jar - this is the JSR-94 compliant implementation, this is essentially a layer over the
drools-compiler component. Note that due to the nature of the JSR-94 specification, not all features are easily
exposed via this interface. In some cases, it will be easier to go direct to the Drools API, but in some
environments the JSR-94 is mandated.

drools-decisiontables.jar - this is the decision tables 'compiler' component, which uses the
drools-compiler component. This supports both excel and CSV input formats.

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.

3.1.2. Runtime

The "runtime" requirements mentioned here are if you are deploying rules as their binary form (either as
KnowledgePackage objects, or KnowledgeBase objects etc). This is an optional feature that allows you to keep your
runtime very light. You may use drools-compiler to produce rule packages "out of process", and then deploy them to a
runtime system. This runtime system only requires drools-core.jar and knowledge-api for execution. This is an optional
deployment pattern, and many people do not need to "trim" their application this much, but it is an ideal option for
certain environments.

3.1.3. Installing IDE (Rule Workbench)

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.

3.1.3.1. Installing GEF (a required dependency)

GEF is the Eclipse Graphical Editing Framework, which is used for graph viewing components in the
plug-in.

If you don't have GEF installed, you can install it using the built in update mechanism (or downloading GEF
from the Eclipse.org website not recommended). JBoss IDE has GEF already, as do many other "distributions" of
Eclipse, so this step may be redundant for some people.

Open the Help->Software updates...->Available Software->Add Site... from the help menu. Location
is:

http://download.eclipse.org/tools/gef/updates/releases/

Next you choose the GEF plug-in:

Press next, and agree to install the plug-in (an Eclipse restart may be required). Once this is completed,
then you can continue on installing the rules plug-in.

3.1.3.2. Installing GEF from zip file

To install from the zip file, download and unzip the file. Inside the zip you will see a plug-in directory,
and the plug-in jar itself. You place the plug-in jar into your Eclipse applications plug-in directory, and
restart Eclipse.

3.1.3.3. Installing Drools plug-in from zip file

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:

3.1.3.4. Drools Runtimes

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.

3.1.3.4.1. Defining a Drools runtime

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:

If you simply want to use the default jars as included in the Drools Eclipse plugin, you can create a
new Drools runtime automatically by clicking the "Create a new Drools 5 runtime ..." button. A file browser
will show up, asking you to select the folder on your file system where you want this runtime to be created.
The plugin will then automatically copy all required dependencies to the specified folder. After selecting
this folder, the dialog should look like the figure shown below.

If you want to use one specific release of the Drools project, you should create a folder on your file
system that contains all the necessary Drools libraries and dependencies. Instead of creating a new Drools
runtime as explained above, give your runtime a name and select the location of this folder containing all
the required jars.

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.

3.1.3.4.2. Selecting a runtime for your Drools project

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.

3.2. Building from source

3.2.1. Getting the sources

The source code of each maven artifact is available in the JBoss maven repository as a source jar. The same
source jars are also included in the download zips. However, if you want to build from source, it's highly
recommended to get our sources from our source control.

Drools and jBPM use Git for source control. The blessed git
repositories are hosted on Github:

Git allows you to fork our code, independently make personal changes on it, yet still merge in our latest
changes regularly and optionally share your changes with us. To learn more about git, read the free book Git Pro.

3.2.2. Building the sources

In essense, building from source is very easy, for example if you want to build the
guvnor project:

3.3. Eclipse

3.3.1. Importing Eclipse Projects

With the Eclipse project files generated they can now be imported into Eclipse. When starting Eclipse open the
workspace in the root of your subversion checkout.

When calling mvn install all the project dependencies were downloaded and added to the
local Maven repository. Eclipse cannot find those dependencies unless you tell it where that repository is. To do
this setup an M2_REPO classpath variable.