Drools Documentation

The previous pattern will match if and only if the temporal distance between the time when $eventB finished and the time when $eventA started is between ( 3 minutes and 30 seconds ) and ( 4 minutes ). In other words:

$eventA : EventA( this after[ 3m30s, 4m ] $eventB )

 3m30s <= $eventA.startTimestamp - $eventB.endTimeStamp <= 4m

The temporal distance interval for the after operator is optional:

If two values are defined (like in the example below), the interval starts on the first value and finishes on the second.
If only one value is defined, the interval starts on the value and finishes on the positive infinity.
If no value is defined, it is assumed that the initial value is 1ms and the final value is the positive infinity.

Note

It is possible to define negative distances for this operator. Example:

$eventA : EventA( this after[ -3m30s, -2m ] $eventB )

Note

If the first value is greater than the second value, the engine automatically reverses them, as there is no reason to have the first value greater than the second value. Example: the following two patterns are considered to have the same semantics:

$eventA : EventA( this after[ -3m30s, -2m ] $eventB ) 
$eventA : EventA( this after[ -2m, -3m30s ] $eventB )

Note

The after, before and coincides operators can be used to define constraints between events, java.util.Date attributes, and long attributes (interpreted as timestamps since epoch) in any combination. Example:

EventA( this after $someDate )

9.9.1.2. Before

The before evaluator correlates two events and matches when the temporal distance from the event being correlated to the current correlated belongs to the distance range declared for the operator.

The previous pattern will match if and only if the temporal distance between the time when $eventA finished and the time when $eventB started is between ( 3 minutes and 30 seconds ) and ( 4 minutes ). In other words:

$eventA : EventA( this before[ 3m30s, 4m ] $eventB )

 3m30s <= $eventB.startTimestamp - $eventA.endTimeStamp <= 4m

The temporal distance interval for the before operator is optional:

If two values are defined (like in the example below), the interval starts on the first value and finishes on the second.
If only one value is defined, then the interval starts on the value and finishes on the positive infinity.
If no value is defined, it is assumed that the initial value is 1ms and the final value is the positive infinity.

Note

It is possible to define negative distances for this operator. Example:

$eventA : EventA( this before[ -3m30s, -2m ] $eventB )

Note

$eventA : EventA( this before[ -3m30s, -2m ] $eventB ) 
$eventA : EventA( this before[ -2m, -3m30s ] $eventB )

Note

EventA( this after $someDate )

9.9.1.3. Coincides

The coincides evaluator correlates two events and matches when both happen at the same time. Optionally, the evaluator accept thresholds for the distance between events' start and finish timestamps.

The previous pattern will match if and only if the start timestamps of both $eventA and $eventB are the same AND the end timestamp of both $eventA and $eventB also are the same.

$eventA : EventA( this coincides $eventB )

Optionally, this operator accepts one or two parameters. These parameters are the thresholds for the distance between matching timestamps.

If only one parameter is given, it is used for both start and end timestamps.
If two parameters are given, then the first is used as a threshold for the start timestamp and the second one is used as a threshold for the end timestamp.

Above pattern will match if and only if:

$eventA : EventA( this coincides[15s, 10s] $eventB )

abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 15s && 
abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 10s

Warning

It makes no sense to use negative interval values for the parameters and the engine will raise an error if that happens.

Note

EventA( this after $someDate )

9.9.1.4. During

The during evaluator correlates two events and matches when the current event happens during the occurrence of the event being correlated.

The previous pattern will match if and only if the $eventA starts after $eventB starts and finishes before $eventB finishes.

$eventA : EventA( this during $eventB )

The during operator accepts 1, 2 or 4 optional parameters as follow:

$eventB.startTimestamp < $eventA.startTimestamp <= $eventA.endTimestamp < $eventB.endTimestamp

If one value is defined, this will be the maximum distance between the start timestamp of both event and the maximum distance between the end timestamp of both events in order to operator match. Example:
```
$eventA : EventA( this during[ 5s ] $eventB )
```
Will match if and only if:
```
0 < $eventA.startTimestamp - $eventB.startTimestamp <= 5s && 
0 < $eventB.endTimestamp - $eventA.endTimestamp <= 5s
```

If two values are defined, the first value will be the minimum distance between the timestamps of both events, while the second value will be the maximum distance between the timestamps of both events. Example:
```
$eventA : EventA( this during[ 5s, 10s ] $eventB )
```
Will match if and only if:
```
5s <= $eventA.startTimestamp - $eventB.startTimestamp <= 10s && 
5s <= $eventB.endTimestamp - $eventA.endTimestamp <= 10s
```

If four values are defined, the first two values will be the minimum and maximum distances between the start timestamp of both events, while the last two values will be the minimum and maximum distances between the end timestamp of both events. Example:
```
$eventA : EventA( this during[ 2s, 6s, 4s, 10s ] $eventB )
```
Will match if and only if:
```
2s <= $eventA.startTimestamp - $eventB.startTimestamp <= 6s && 
4s <= $eventB.endTimestamp - $eventA.endTimestamp <= 10s
```

9.9.1.5. Finishes

The finishes evaluator correlates two events and matches when the current event's start timestamp happens after the correlated event's start timestamp, but both end timestamps occur at the same time.

The previous pattern will match if and only if the $eventA starts after $eventB starts and finishes at the same time $eventB finishes.

$eventA : EventA( this finishes $eventB )

The finishes evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the end timestamp of both events in order for the operator to match. Example:

$eventB.startTimestamp < $eventA.startTimestamp && 
$eventA.endTimestamp == $eventB.endTimestamp

$eventA : EventA( this finishes[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

$eventB.startTimestamp < $eventA.startTimestamp && 
abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 5s

Warning

9.9.1.6. Finished By

The finishedby evaluator correlates two events and matches when the current event start timestamp happens before the correlated event start timestamp, but both end timestamps occur at the same time. This is the symmetrical opposite of finishes evaluator.

The previous pattern will match if and only if the $eventA starts before $eventB starts and finishes at the same time $eventB finishes.

$eventA : EventA( this finishedby $eventB )

The finishedby evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the end timestamp of both events in order for the operator to match. Example:

$eventA.startTimestamp < $eventB.startTimestamp && 
$eventA.endTimestamp == $eventB.endTimestamp

$eventA : EventA( this finishedby[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

$eventA.startTimestamp < $eventB.startTimestamp && 
abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 5s

Warning

9.9.1.7. Includes

The includes evaluator correlates two events and matches when the event being correlated happens during the current event. It is the symmetrical opposite of during evaluator.

The previous pattern will match if and only if the $eventB starts after $eventA starts and finishes before $eventA finishes.

$eventA : EventA( this includes $eventB )

The includes operator accepts 1, 2 or 4 optional parameters as follow:

$eventA.startTimestamp < $eventB.startTimestamp <= $eventB.endTimestamp < $eventA.endTimestamp

If one value is defined, this will be the maximum distance between the start timestamp of both event and the maximum distance between the end timestamp of both events in order to operator match. Example:
```
$eventA : EventA( this includes[ 5s ] $eventB )
```
Will match if and only if:
```
0 < $eventB.startTimestamp - $eventA.startTimestamp <= 5s && 
0 < $eventA.endTimestamp - $eventB.endTimestamp <= 5s
```

If two values are defined, the first value will be the minimum distance between the timestamps of both events, while the second value will be the maximum distance between the timestamps of both events. Example:
```
$eventA : EventA( this includes[ 5s, 10s ] $eventB )
```
Will match if and only if:
```
5s <= $eventB.startTimestamp - $eventA.startTimestamp <= 10s && 
5s <= $eventA.endTimestamp - $eventB.endTimestamp <= 10s
```

If four values are defined, the first two values will be the minimum and maximum distances between the start timestamp of both events, while the last two values will be the minimum and maximum distances between the end timestamp of both events. Example:
```
$eventA : EventA( this includes[ 2s, 6s, 4s, 10s ] $eventB )
```
Will match if and only if:
```
2s <= $eventB.startTimestamp - $eventA.startTimestamp <= 6s && 
4s <= $eventA.endTimestamp - $eventB.endTimestamp <= 10s 
```

9.9.1.8. Meets

The meets evaluator correlates two events and matches when the current event's end timestamp happens at the same time as the correlated event's start timestamp.

The previous pattern will match if and only if the $eventA finishes at the same time $eventB starts.

$eventA : EventA( this meets $eventB )

The meets evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the end timestamp of current event and the start timestamp of the correlated event in order for the operator to match. Example:

abs( $eventB.startTimestamp - $eventA.endTimestamp ) == 0

$eventA : EventA( this meets[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

abs( $eventB.startTimestamp - $eventA.endTimestamp) <= 5s

Warning

9.9.1.9. Met By

The metby evaluator correlates two events and matches when the current event's start timestamp happens at the same time as the correlated event's end timestamp.

The previous pattern will match if and only if the $eventA starts at the same time $eventB finishes.

$eventA : EventA( this metby $eventB )

The metby evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the end timestamp of the correlated event and the start timestamp of the current event in order for the operator to match. Example:

abs( $eventA.startTimestamp - $eventB.endTimestamp ) == 0

$eventA : EventA( this metby[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

abs( $eventA.startTimestamp - $eventB.endTimestamp) <= 5s

Warning

9.9.1.10. Overlaps

The overlaps evaluator correlates two events and matches when the current event starts before the correlated event starts and finishes after the correlated event starts, but before the correlated event finishes. In other words, both events have an overlapping period.

The previous pattern will match if and only if:

$eventA : EventA( this overlaps $eventB )

$eventA.startTimestamp < $eventB.startTimestamp < $eventA.endTimestamp < $eventB.endTimestamp

The overlaps operator accepts 1 or 2 optional parameters as follow:

If one parameter is defined, this will be the maximum distance between the start timestamp of the correlated event and the end timestamp of the current event. Example:
```
$eventA : EventA( this overlaps[ 5s ] $eventB )
```
Will match if and only if:
```
$eventA.startTimestamp < $eventB.startTimestamp < $eventA.endTimestamp < $eventB.endTimestamp && 
0 <= $eventA.endTimestamp - $eventB.startTimestamp <= 5s
```

If two values are defined, the first value will be the minimum distance and the second value will be the maximum distance between the start timestamp of the correlated event and the end timestamp of the current event. Example:
```
$eventA : EventA( this overlaps[ 5s, 10s ] $eventB )
```
Will match if and only if:
```
$eventA.startTimestamp < $eventB.startTimestamp < $eventA.endTimestamp < $eventB.endTimestamp && 
5s <= $eventA.endTimestamp - $eventB.startTimestamp <= 10s 
```

9.9.1.11. Overlapped By

The overlappedby evaluator correlates two events and matches when the correlated event starts before the current event starts and finishes after the current event starts, but before the current event finishes. In other words, both events have an overlapping period.

The previous pattern will match if and only if:

$eventA : EventA( this overlappedby $eventB )

$eventB.startTimestamp < $eventA.startTimestamp < $eventB.endTimestamp < $eventA.endTimestamp

The overlappedby operator accepts 1 or 2 optional parameters as follow:

If one parameter is defined, this will be the maximum distance between the start timestamp of the current event and the end timestamp of the correlated event. Example:
```
$eventA : EventA( this overlappedby[ 5s ] $eventB )
```
Will match if and only if:
```
$eventB.startTimestamp < $eventA.startTimestamp < $eventB.endTimestamp < $eventA.endTimestamp && 
0 <= $eventB.endTimestamp - $eventA.startTimestamp <= 5s
```

If two values are defined, the first value will be the minimum distance and the second value will be the maximum distance between the start timestamp of the current event and the end timestamp of the correlated event. Example:
```
$eventA : EventA( this overlappedby[ 5s, 10s ] $eventB )
```
Will match if and only if:
```
$eventB.startTimestamp < $eventA.startTimestamp < $eventB.endTimestamp < $eventA.endTimestamp && 
5s <= $eventB.endTimestamp - $eventA.startTimestamp <= 10s
```

9.9.1.12. Starts

The starts evaluator correlates two events and matches when the current event's end timestamp happens before the correlated event's end timestamp, but both start timestamps occur at the same time.

The previous pattern will match if and only if the $eventA finishes before $eventB finishes and starts at the same time $eventB starts.

$eventA : EventA( this starts $eventB )

The starts evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the start timestamp of both events in order for the operator to match. Example:

$eventA.startTimestamp == $eventB.startTimestamp && 
$eventA.endTimestamp < $eventB.endTimestamp

$eventA : EventA( this starts[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 5s && 
$eventA.endTimestamp < $eventB.endTimestamp

Warning

9.9.1.13. Started By

The startedby evaluator correlates two events and matches when the correlating event's end timestamp happens before the current event's end timestamp, but both start timestamps occur at the same time. Lets look at an example:

$eventA : EventA( this startedby $eventB )

The previous pattern will match if and only if the $eventB finishes before $eventA finishes and starts at the same time $eventB starts.

The startedby evaluator accepts one optional parameter. If it is defined, it determines the maximum distance between the start timestamp of both events in order for the operator to match. Example:

$eventA.startTimestamp == $eventB.startTimestamp && 
$eventA.endTimestamp > $eventB.endTimestamp

$eventA : EventA( this starts[ 5s ] $eventB )

It makes no sense to use a negative interval value for the parameter and the engine will raise an exception if that happens.

abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 5s && 
$eventA.endTimestamp > $eventB.endTimestamp

Warning

Chapter 10. Experimental Features

10.1. Declarative Agenda

10.2. Browsing graphs of objects with OOPath

10.2.1. Reactive and Non-Reactive OOPath

10.1. Declarative Agenda

Warning

Declarative Agenda is experimental, and all aspects are highly likely to change in the future. @Eager and @Direct are temporary annotations to control the behaviour of rules, which will also change as Declarative Agenda evolves. Annotations instead of attributes where chosen, to reflect their experimental nature.

The declarative agenda allows to use rules to control which other rules can fire and when. While this will add a lot more overhead than the simple use of salience, the advantage is it is declarative and thus more readable and maintainable and should allow more use cases to be achieved in a simpler fashion.

This feature is off by default and must be explicitly enabled, that is because it is considered highly experimental for the moment and will be subject to change, but can be activated on a given KieBase by adding the declarativeAgenda='enabled' attribute in the corresponding kbase tag of the kmodule.xml file as in the following example.

Example 10.1. Enabling the Declarative Agenda

<kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns="http://www.drools.org/xsd/kmodule">
      <kbase name="DeclarativeKBase" declarativeAgenda="enabled">
      <ksession name="KSession">
      </kbase>
      </kmodule>

The basic idea is:

All rule's Matches are inserted into WorkingMemory as facts. So you can now do pattern matching against a Match. The rule's metadata and declarations are available as fields on the Match object.
You can use the kcontext.blockMatch( Match match ) for the current rule to block the selected match. Only when that rule becomes false will the match be eligible for firing. If it is already eligible for firing and is later blocked, it will be removed from the agenda until it is unblocked.
A match may have multiple blockers and a count is kept. All blockers must became false for the counter to reach zero to enable the Match to be eligible for firing.
kcontext.unblockAllMatches( Match match ) is an over-ride rule that will remove all blockers regardless
An activation may also be cancelled, so it never fires with cancelMatch
An unblocked Match is added to the Agenda and obeys normal salience, agenda groups, ruleflow groups etc.
The @Direct annotations allows a rule to fire as soon as it's matched, this is to be used for rules that block/unblock matches, it is not desirable for these rules to have side effects that impact else where.

Example 10.2. New RuleContext methods

void blockMatch(Match match);
      void unblockAllMatches(Match match);
      void cancelMatch(Match match);

Here is a basic example that will block all matches from rules that have metadata @department('sales'). They will stay blocked until the blockerAllSalesRules rule becomes false, i.e. "go2" is retracted.

Example 10.3. Block rules based on rule metadata

rule rule1 @Eager @department('sales') when
      $s : String( this == 'go1' )
      then
      list.add( kcontext.rule.name + ':' + $s );
      end
      rule rule2 @Eager @department('sales') when
      $s : String( this == 'go1' )
      then
      list.add( kcontext.rule.name + ':' + $s );
      end
      rule blockerAllSalesRules @Direct @Eager when
      $s : String( this == 'go2' )
      $i : Match( department == 'sales' )
      then
      list.add( $i.rule.name + ':' + $s  );
      kcontext.blockMatch( $i );
      end

Warning

Further than annotate the blocking rule with @Direct, it is also necessary to annotate all the rules that could be potentially blocked by it with @Eager. This is because, since the Match has to be evaluated by the pattern matching of the blocking rule, the potentially blocked ones cannot be evaluated lazily, otherwise won't be any Match to be evaluated.

This example shows how you can use active property to count the number of active or inactive (already fired) matches.

Example 10.4. Count the number of active/inactive Matches

rule rule1 @Eager @department('sales') when
      $s : String( this == 'go1' )
      then
      list.add( kcontext.rule.name + ':' + $s );
      end
      rule rule2 @Eager @department('sales') when
      $s : String( this == 'go1' )
      then
      list.add( kcontext.rule.name + ':' + $s );
      end
      rule rule3 @Eager @department('sales') when
      $s : String( this == 'go1' )
      then
      list.add( kcontext.rule.name + ':' + $s );
      end
      rule countActivateInActive @Direct @Eager when
      $s : String( this == 'go2' )
      $active : Number( this == 1 ) from accumulate( $a : Match( department == 'sales', active == true ), count( $a ) )
      $inActive : Number( this == 2 ) from  accumulate( $a : Match( department == 'sales', active == false ), count( $a ) )
      then
      kcontext.halt( );
      end

10.2. Browsing graphs of objects with OOPath

Example 10.5. Browsing a graph of objects with from

rule "Find all grades for Big Data exam" when
      $student: Student( $plan: plan )
      $exam: Exam( course == "Big Data" ) from $plan.exams
      $grade: Grade() from $exam.grades
      then /* RHS */ end

Example 10.6. Browsing a graph of objects with OOPath

rule "Find all grades for Big Data exam" when
      Student( $grade: /plan/exams{course == "Big Data"}/grades )
      then /* RHS */ end

Formally, the core grammar of an OOPath expression can be defined in EBNF notation in this way.

OOPExpr = ( "/" | "?/" ) OOPSegment { ( "/" | "?/" | "." ) OOPSegment } ;
    OOPSegment = [ID ( ":" | ":=" )] ID ["[" Number "]"] ["{" Constraints "}"];

In practice an OOPath expression has the following features.

It has to start with / or with a ?/ in case of a completely non-reactive OOPath (see below).
It can dereference a single property of an object with the . operator
It can dereference a multiple property of an object using the / operator. If a collection is returned, it will iterate over the values in the collection
While traversing referenced objects it can filter away those not satisfying one or more constraints, written as predicate expressions between curly brackets like in:
```
Student( $grade: /plan/exams{ course == "Big Data" }/grades )
```
A constraint can also have a beckreference to an object of the graph traversed before the currently iterated one. For example the following OOPath:
```
Student( $grade: /plan/exams/grades{ result > ../averageResult } )
```
will match only the grades having a result above the average for the passed exam.
A constraint can also recursively be another OOPath as it follows:
```
Student( $exam: /plan/exams{ /grades{ result > 20 } } )
```
Items can also be accessed by their index by putting it between square brackets like in:
```
Student( $grade: /plan/exams[0]/grades )
```
To adhere to Java convention OOPath indexes are 0-based, compared to XPath 1-based

10.2.1. Reactive and Non-Reactive OOPath

At the moment Drools is not able to react to updates involving a deeply nested object traversed during the evaluation of an OOPath expression. To make these objects reactive to changes it is then necessary to make them extend the class org.drools.core.phreak.ReactiveObject. It is planned to overcome this limitation by implementing a mechanism that automatically instruments the classes belonging to a specific domain model.

Having extendend that class, the domain objects can notify the engine when one of its field has been updated by invoking the inherited method notifyModification as in the following example:

Example 10.7. Notifying the engine that an exam has been moved to a different course

public void setCourse(String course) {
        this.course = course;
        notifyModification(this);
        }

In this way when using an OOPath like the following:

Student( $grade: /plan/exams{ course == "Big Data" }/grades )

if an exam is moved to a different course, the rule is re-triggered and the list of grades matching the rule recomputed.

It is also possible to have reactivity only in one subpart of the OOPath as in:

Student( $grade: /plan/exams{ course == "Big Data" }?/grades )

Here, using the ?/ separator instead of the / one, the engine will react to a change made to an exam, or if an exam is added to the plan, but not if a new grade is added to an existing exam. Of course if a OOPath chunk is not reactive, all remaining part of the OOPath from there till the end of the expression will be non-reactive as well. For instance the following OOPath

Student( $grade: ?/plan/exams{ course == "Big Data" }/grades )

will be completely non-reactive. For this reason it is not allowed to use the ?/ separator more than once in the same OOPath so an expression like:

Student( $grade: /plan?/exams{ course == "Big Data" }?/grades )

will cause a compile time error.

Part IV. Drools Integration

Integration Documentation

Table of Contents

11. Drools Commands

11.1. API

11.1.1. XStream
11.1.2. JSON
11.1.3. JAXB

11.2. Commands supported

11.2.1. BatchExecutionCommand
11.2.2. InsertObjectCommand
11.2.3. RetractCommand
11.2.4. ModifyCommand
11.2.5. GetObjectCommand
11.2.6. InsertElementsCommand
11.2.7. FireAllRulesCommand
11.2.8. StartProcessCommand
11.2.9. SignalEventCommand
11.2.10. CompleteWorkItemCommand
11.2.11. AbortWorkItemCommand
11.2.12. QueryCommand
11.2.13. SetGlobalCommand
11.2.14. GetGlobalCommand
11.2.15. GetObjectsCommand

12. CDI

12.1. Introduction

12.2. Annotations

12.2.1. @KReleaseId
12.2.2. @KContainer
12.2.3. @KBase
12.2.4. @KSession for KieSession
12.2.5. @KSession for StatelessKieSession

12.3. API Example Comparison

13. Integration with Spring

13.1. Important Changes for Drools 6.0

13.2. Integration with Drools Expert

13.2.1. KieModule
13.2.2. KieBase
13.2.3. IMPORTANT NOTE
13.2.4. KieSessions
13.2.5. Kie:ReleaseId
13.2.6. Kie:Import
13.2.7. Annotations
13.2.8. Event Listeners
13.2.9. Loggers
13.2.10. Defining Batch Commands
13.2.11. Persistence
13.2.12. Leveraging Other Spring Features

13.3. Integration with jBPM Human Task

13.3.1. How to configure Spring with jBPM Human task

14. Android Integration

14.1. Integration with Drools Expert

14.1.1. Pre-serialized Rules
14.1.2. KieContainer API with drools-compiler dependency

14.2. Integration with Roboguice

14.2.1. Pre-serialized Rules with Roboguice
14.2.2. KieContainer with drools-compiler dependency and Roboguice

15. Apache Camel Integration

15.1. Camel

16. Drools Camel Server

16.1. Introduction

16.2. Deployment

16.3. Configuration

16.3.1. REST/Camel Services configuration

17. JMX monitoring with RHQ/JON

17.1. Introduction

17.1.1. Enabling JMX monitoring in a Drools application
17.1.2. Installing and running the RHQ/JON plugin

Chapter 11. Drools Commands

11.1. API

XML marshalling/unmarshalling of the Drools Commands requires the use of special classes, which are going to be described in the following sections.

The following urls show sample script examples for jaxb, xstream and json marshalling using:

http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD
http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/jaxb.mvt?r=HEAD
http://fisheye.jboss.org/browse/JBossRules/trunk/drools-camel/src/test/resources/org/drools/camel/component/xstream.mvt?r=HEAD

11.1.1. XStream

To use the XStream commands marshaller you need to use the DroolsHelperProvider to obtain an XStream instance. We need to use this because it has the commands converters registered.

Marshalling
BatchExecutionHelperProviderImpl.newXStreamMarshaller().toXML(command);
Unmarshalling
BatchExecutionHelperProviderImpl.newXStreamMarshaller().fromXML(xml)

11.1.2. JSON

JSON API to marshalling/unmarshalling is similar to XStream API:

Marshalling
BatchExecutionHelper.newJSonMarshaller().toXML(command);
Unmarshalling
BatchExecutionHelper.newJSonMarshaller().fromXML(xml)

11.1.3. JAXB

There are two options for using JAXB, you can define your model in an XSD file or you can have a POJO model. In both cases you have to declare your model inside JAXBContext, and in order to do that you need to use Drools Helper classes. Once you have the JAXBContext you need to create the Unmarshaller/Marshaller as needed.

11.1.3.1. Using an XSD file to define the model

With your model defined in a XSD file you need to have a KnowledgeBase that has your XSD model added as a resource.

To do this, the XSD file must be added as a XSD ResourceType into the KnowledgeBuilder. Finally you can create the JAXBContext using the KnowledgeBase created with the KnowledgeBuilder  

Options xjcOpts = new Options();
xjcOpts.setSchemaLanguage(Language.XMLSCHEMA);
JaxbConfiguration jaxbConfiguration = KnowledgeBuilderFactory.newJaxbConfiguration( xjcOpts, "xsd" );
kbuilder.add(ResourceFactory.newClassPathResource("person.xsd", getClass()), ResourceType.XSD, jaxbConfiguration);
KnowledgeBase kbase = kbuilder.newKnowledgeBase();

List<String> classesName = new ArrayList<String>();
classesName.add("org.drools.compiler.test.Person");
   
JAXBContext jaxbContext = KnowledgeBuilderHelper.newJAXBContext(classesName.toArray(new String[classesName.size()]), kbase);

11.1.3.2. Using a POJO model

In this case you need to use DroolsJaxbHelperProviderImpl to create the JAXBContext. This class has two parameters:

classNames: A List with the canonical name of the classes that you want to use in the marshalling/unmarshalling process.
properties: JAXB custom properties

List<String> classNames = new ArrayList<String>();
classNames.add("org.drools.compiler.test.Person");
JAXBContext jaxbContext = DroolsJaxbHelperProviderImpl.createDroolsJaxbContext(classNames, null);
Marshaller marshaller = jaxbContext.createMarshaller();

11.2. Commands supported

Currently, the following commands are supported:

BatchExecutionCommand
InsertObjectCommand
RetractCommand
ModifyCommand
GetObjectCommand
InsertElementsCommand
FireAllRulesCommand
StartProcessCommand
SignalEventCommand
CompleteWorkItemCommand
AbortWorkItemCommand
QueryCommand
SetGlobalCommand
GetGlobalCommand
GetObjectsCommand

Note

In the next snippets code we are going to use a POJO org.drools.compiler.test.Person that has two fields

name: String
age: Integer

Note

In the next examples, to marshall the commands we have used the next snippet codes:

String xml = BatchExecutionHelper.newXStreamMarshaller().toXML(command);

String xml = BatchExecutionHelper.newJSonMarshaller().toXML(command);

Marshaller marshaller = jaxbContext.createMarshaller();
StringWriter xml = new StringWriter();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.marshal(command, xml);

11.2.1. BatchExecutionCommand

Description: The command that contains a list of commands, which will be sent and executed.
Attributes
Table 11.1. BatchExecutionCommand attributes
Name Description required
lookup Sets the knowledge session id on which the commands are going to be executed true
commands List of commands to be executed false

Name	Description	required
lookup	Sets the knowledge session id on which the commands are going to be executed	true
commands	List of commands to be executed	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
InsertObjectCommand insertObjectCommand = new InsertObjectCommand(new Person("john", 25));
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
command.getCommands().add(insertObjectCommand);
command.getCommands().add(fireAllRulesCommand);

<batch-execution lookup="ksession1">
  <insert>
    <org.drools.compiler.test.Person>
      <name>john</name>
      <age>25</age>
    </org.drools.compiler.test.Person>
  </insert>
  <fire-all-rules/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":[{"insert":{"object":{"org.drools.compiler.test.Person":{"name":"john","age":25}}}},{"fire-all-rules":""}]}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <insert>
        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <age>25</age>
            <name>john</name>
        </object>
    </insert>
    <fire-all-rules max="-1"/>
</batch-execution>

11.2.2. InsertObjectCommand

Description: Insert an object in the knowledge session.

Table 11.2. InsertObjectCommand attributes

Name	Description	required
object	The object to be inserted	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false
returnObject	Boolean to establish if the object must be returned in the execution results. Default value: true	false
entryPoint	Entrypoint for the insertion	false

List<Command> cmds = ArrayList<Command>();

Command insertObjectCommand = CommandFactory.newInsert(new Person("john", 25), "john", false, null);
cmds.add( insertObjectCommand );

BatchExecutionCommand command = CommandFactory.createBatchExecution(cmds, "ksession1" );

<batch-execution lookup="ksession1">
  <insert out-identifier="john" entry-point="my stream" return-object="false">
    <org.drools.compiler.test.Person>
      <name>john</name>
      <age>25</age>
    </org.drools.compiler.test.Person>
  </insert>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"insert":{"entry-point":"my stream", "out-identifier":"john","return-object":false,"object":{"org.drools.compiler.test.Person":{"name":"john","age":25}}}}}}

Command creation: we have two options, with the same output result:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <insert out-identifier="john" entry-point="my stream" >
        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <age>25</age>
            <name>john</name>
        </object>
    </insert>
</batch-execution>

11.2.3. RetractCommand

Description: Retract an object from the knowledge session.
Attributes
Table 11.3. RetractCommand attributes
Name Description required
handle The FactHandle associated to the object to be retracted true

Name	Description	required
handle	The FactHandle associated to the object to be retracted	true

Create the Fact Handle from a string

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
RetractCommand retractCommand = new RetractCommand();
retractCommand.setFactHandleFromString("123:234:345:456:567");
command.getCommands().add(retractCommand);

Set the Fact Handle that you received when the object was inserted

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
RetractCommand retractCommand = new RetractCommand(factHandle);
command.getCommands().add(retractCommand);

<batch-execution lookup="ksession1">
  <retract fact-handle="0:234:345:456:567"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"retract":{"fact-handle":"0:234:345:456:567"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <retract fact-handle="0:234:345:456:567"/>
</batch-execution>

11.2.4. ModifyCommand

Description: Allows you to modify a previously inserted object in the knowledge session.
Attributes
Table 11.4. ModifyCommand attributes
Name Description required
handle The FactHandle associated to the object to be retracted true
setters List of setters object's modifications true

Name	Description	required
handle	The FactHandle associated to the object to be retracted	true
setters	List of setters object's modifications	true

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
ModifyCommand modifyCommand = new ModifyCommand();
modifyCommand.setFactHandleFromString("123:234:345:456:567");
List<Setter> setters = new ArrayList<Setter>();
setters.add(new SetterImpl("age", "30"));
modifyCommand.setSetters(setters);
command.getCommands().add(modifyCommand);

<batch-execution lookup="ksession1">
  <modify fact-handle="0:234:345:456:567">
    <set accessor="age" value="30"/>
  </modify>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"modify":{"fact-handle":"0:234:345:456:567","setters":{"accessor":"age","value":30}}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <modify fact-handle="0:234:345:456:567">
        <set value="30" accessor="age"/>
    </modify>
</batch-execution>

11.2.5. GetObjectCommand

Description: Used to get an object from a knowledge session

Table 11.5. GetObjectCommand attributes

Name	Description	required
factHandle	The FactHandle associated to the object to be retracted	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
GetObjectCommand getObjectCommand = new GetObjectCommand();
getObjectCommand.setFactHandleFromString("123:234:345:456:567");
getObjectCommand.setOutIdentifier("john");
command.getCommands().add(getObjectCommand);

<batch-execution lookup="ksession1">
  <get-object fact-handle="0:234:345:456:567" out-identifier="john"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"get-object":{"fact-handle":"0:234:345:456:567","out-identifier":"john"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <get-object out-identifier="john" fact-handle="0:234:345:456:567"/>
</batch-execution>

11.2.6. InsertElementsCommand

Description: Used to insert a list of objects.

Table 11.6. InsertElementsCommand attributes

Name	Description	required
objects	The list of objects to be inserted on the knowledge session	true
outIdentifier	Id to identify the FactHandle created in the object insertion and added to the execution results	false
returnObject	Boolean to establish if the object must be returned in the execution results. Default value: true	false
entryPoint	Entrypoint for the insertion	false

List<Command> cmds = ArrayList<Command>();

List<Object> objects = new ArrayList<Object>();
objects.add(new Person("john", 25));
objects.add(new Person("sarah", 35));

Command insertElementsCommand = CommandFactory.newInsertElements( objects );
cmds.add( insertElementsCommand );

BatchExecutionCommand command = CommandFactory.createBatchExecution(cmds, "ksession1" );

<batch-execution lookup="ksession1">
  <insert-elements>
    <org.drools.compiler.test.Person>
      <name>john</name>
      <age>25</age>
    </org.drools.compiler.test.Person>
    <org.drools.compiler.test.Person>
      <name>sarah</name>
      <age>35</age>
    </org.drools.compiler.test.Person>
  </insert-elements>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"insert-elements":{"objects":[{"containedObject":{"@class":"org.drools.compiler.test.Person","name":"john","age":25}},{"containedObject":{"@class":"Person","name":"sarah","age":35}}]}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <insert-elements return-objects="true">
        <list>
            <element xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <age>25</age>
                <name>john</name>
            </element>
            <element xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                <age>35</age>
                <name>sarah</name>
            </element>
        <list>
    </insert-elements>
</batch-execution>

11.2.7. FireAllRulesCommand

Description: Allow execution of the rules activations created.

Table 11.7. FireAllRulesCommand attributes

Name	Description	required
max	The max number of rules activations to be executed. default is -1 and will not put any restriction on execution	false
outIdentifier	Add the number of rules activations fired on the execution results	false
agendaFilter	Allow the rules execution using an Agenda Filter	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
FireAllRulesCommand fireAllRulesCommand = new FireAllRulesCommand();
fireAllRulesCommand.setMax(10);
fireAllRulesCommand.setOutIdentifier("firedActivations");
command.getCommands().add(fireAllRulesCommand);

<batch-execution lookup="ksession1">
  <fire-all-rules max="10" out-identifier="firedActivations"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"fire-all-rules":{"max":10,"out-identifier":"firedActivations"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
   <fire-all-rules out-identifier="firedActivations" max="10"/>
</batch-execution>

11.2.8. StartProcessCommand

Description: Allows you to start a process using the ID. Also you can pass parameters and initial data to be inserted.

Table 11.8. StartProcessCommand attributes

Name	Description	required
processId	The ID of the process to be started	true
parameters	A Map<String, Object> to pass parameters in the process startup	false
data	A list of objects to be inserted in the knowledge session before the process startup	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
StartProcessCommand startProcessCommand = new StartProcessCommand();
startProcessCommand.setProcessId("org.drools.task.processOne");
command.getCommands().add(startProcessCommand);

<batch-execution lookup="ksession1">
  <start-process processId="org.drools.task.processOne"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"start-process":{"process-id":"org.drools.task.processOne"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <start-process processId="org.drools.task.processOne">
        <parameter/>
    </start-process>
</batch-execution>

11.2.9. SignalEventCommand

Description: Send a signal event.
Attributes
Table 11.9. SignalEventCommand attributes
Name Description required
event-type true
processInstanceId false
event false

Name	Description	required
event-type		true
processInstanceId		false
event		false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
SignalEventCommand signalEventCommand = new SignalEventCommand();
signalEventCommand.setProcessInstanceId(1001);
signalEventCommand.setEventType("start");
signalEventCommand.setEvent(new Person("john", 25));
command.getCommands().add(signalEventCommand);

<batch-execution lookup="ksession1">
  <signal-event process-instance-id="1001" event-type="start">
    <org.drools.pipeline.camel.Person>
      <name>john</name>
      <age>25</age>
    </org.drools.pipeline.camel.Person>
  </signal-event>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"signal-event":{"process-instance-id":1001,"@event-type":"start","event-type":"start","object":{"org.drools.pipeline.camel.Person":{"name":"john","age":25}}}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <signal-event event-type="start" process-instance-id="1001">
        <event xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <age>25</age>
            <name>john</name>
        </event>
    </signal-event>
</batch-execution>

11.2.10. CompleteWorkItemCommand

Description: Allows you to complete a WorkItem.
Attributes
Table 11.10. CompleteWorkItemCommand attributes
Name Description required
workItemId The ID of the WorkItem to be completed true
results false

Name	Description	required
workItemId	The ID of the WorkItem to be completed	true
results		false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
CompleteWorkItemCommand completeWorkItemCommand = new CompleteWorkItemCommand();
completeWorkItemCommand.setWorkItemId(1001);
command.getCommands().add(completeWorkItemCommand);

<batch-execution lookup="ksession1">
  <complete-work-item id="1001"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"complete-work-item":{"id":1001}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <complete-work-item id="1001"/>
</batch-execution>

11.2.11. AbortWorkItemCommand

Description: Allows you abort an WorkItem. The same as session.getWorkItemManager().abortWorkItem(workItemId)
Attributes
Table 11.11. AbortWorkItemCommand attributes
Name Description required
workItemId The ID of the WorkItem to be completed true

Name	Description	required
workItemId	The ID of the WorkItem to be completed	true

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
AbortWorkItemCommand abortWorkItemCommand = new AbortWorkItemCommand();
abortWorkItemCommand.setWorkItemId(1001);
command.getCommands().add(abortWorkItemCommand);

<batch-execution lookup="ksession1">
  <abort-work-item id="1001"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"abort-work-item":{"id":1001}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <abort-work-item id="1001"/>
</batch-execution>

11.2.12. QueryCommand

Description: Executes a query defined in knowledge base.

Table 11.12. QueryCommand attributes

Name	Description	required
name	The query name	true
outIdentifier	The identifier of the query results. The query results are going to be added in the execution results with this identifier	false
arguments	A list of objects to be passed as a query parameter	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
QueryCommand queryCommand = new QueryCommand();
queryCommand.setName("persons");
queryCommand.setOutIdentifier("persons");
command.getCommands().add(queryCommand);

<batch-execution lookup="ksession1">
  <query out-identifier="persons" name="persons"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"query":{"out-identifier":"persons","name":"persons"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <query name="persons" out-identifier="persons"/>
</batch-execution>

11.2.13. SetGlobalCommand

Description: Allows you to set a global.

Table 11.13. SetGlobalCommand attributes

Name	Description	required
identifier	The identifier of the global defined in the knowledge base	true
object	The object to be set into the global	false
out	A boolean to add, or not, the set global result into the execution results	false
outIdentifier	The identifier of the global execution result	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
SetGlobalCommand setGlobalCommand = new SetGlobalCommand();
setGlobalCommand.setIdentifier("helper");
setGlobalCommand.setObject(new Person("kyle", 30));
setGlobalCommand.setOut(true);
setGlobalCommand.setOutIdentifier("output");
command.getCommands().add(setGlobalCommand);

<batch-execution lookup="ksession1">
  <set-global identifier="helper" out-identifier="output">
    <org.drools.compiler.test.Person>
      <name>kyle</name>
      <age>30</age>
    </org.drools.compiler.test.Person>
  </set-global>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"set-global":{"identifier":"helper","out-identifier":"output","object":{"org.drools.compiler.test.Person":{"name":"kyle","age":30}}}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <set-global out="true" out-identifier="output" identifier="helper">
        <object xsi:type="person" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <age>30</age>
            <name>kyle</name>
        </object>
    </set-global>
</batch-execution>

11.2.14. GetGlobalCommand

Description: Allows you to get a global previously defined.
Attributes
Table 11.14. GetGlobalCommand attributes
Name Description required
identifier The identifier of the global defined in the knowledge base true
outIdentifier The identifier to be used in the execution results false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
GetGlobalCommand getGlobalCommand = new GetGlobalCommand();
getGlobalCommand.setIdentifier("helper");
getGlobalCommand.setOutIdentifier("helperOutput");
command.getCommands().add(getGlobalCommand);

<batch-execution lookup="ksession1">
  <get-global identifier="helper" out-identifier="helperOutput"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"get-global":{"identifier":"helper","out-identifier":"helperOutput"}}}}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<batch-execution lookup="ksession1">
    <get-global out-identifier="helperOutput" identifier="helper"/>
</batch-execution>

11.2.15. GetObjectsCommand

Description: Returns all the objects from the current session as a Collection.

Table 11.15. GetObjectsCommand attributes

Name	Description	required
objectFilter	An ObjectFilter to filter the objects returned from the current session	false
outIdentifier	The identifier to be used in the execution results	false

BatchExecutionCommand command = new BatchExecutionCommand();
command.setLookup("ksession1");
GetObjectsCommand getObjectsCommand = new GetObjectsCommand();
getObjectsCommand.setOutIdentifier("objects");
command.getCommands().add(getObjectsCommand);

<batch-execution lookup="ksession1">
  <get-objects out-identifier="objects"/>
</batch-execution>

{"batch-execution":{"lookup":"ksession1","commands":{"get-objects":{"out-identifier":"objects"}}}}