Drools Expert User Guide

5.0.1


Table of Contents

1. The Rule Engine
What is a Rule Engine?
Introduction and Background
Why use a Rule Engine?
Advantages of a Rule Engine
When should you use a Rule Engine?
When not to use a Rule Engine
Scripting or Process Engines
Strong and Loose Coupling
2. Quick Start
The Basics
Stateless Knowledge Session
Stateful Knowledge Session
A Little Theory
Methods versus Rules
Cross Products
Activations, Agenda and Conflict Sets.
More on building and deploying
Knowledge Base by Configuration Using Changesets
Knowledge Agent
3. User Guide
Building
Building using Code
Building using Configuration and the ChangeSet XML
Deploying
KnowledgePackage and Knowledge Definitions
KnowledgeBase
In-Process Building and Deployment
Building and Deployment in Separate Processes
StatefulknowledgeSessions and KnowledgeBase Modifications
KnowledgeAgent
Running
KnowledgeBase
StatefulKnowledgeSession
KnowledgeRuntime
Agenda
Event Model
KnowledgeRuntimeLogger
StatelessKnowledgeSession
Pipeline
Commands and the CommandExecutor
Marshalling
Persistence and Transactions
4. The Rule Language
Overview
A rule file
What makes a rule
Keywords
Comments
Single line comment
Multi-line comment
Error Messages
Message format
Error Messages Description
Other Messages
Package
import
global
Function
Type Declaration
Declaring New Types
Declaring Metadata
Declaring Metadata for Existing Types
Accessing Declared Types from the Application Code
Rule
Rule Attributes
Left Hand Side (when) Conditional Elements
The Right Hand Side (then)
A Note on Auto-boxing and Primitive Types
Query
Domain Specific Languages
When to use a DSL
Editing and managing a DSL
Using a DSL in your rules
Adding constraints to facts
How it works
Creating a DSL from scratch
Scope and keywords
DSLs in the BRMS and IDE
XML Rule Language
When to use XML
The XML format
Legacy Drools 2.x XML rule format
Automatic transforming between formats (XML and DRL)
5. Authoring
Decision Tables in Spreadsheets
When to use Decision tables
Overview
How decision tables work
Keywords and Syntax
Creating and integrating Spreadsheet based Decision Tables
Managing business rules in decision tables.
Rule Templates
Templates
The Rule Template File
Expanding a Template
Example
6. The Java Rule Engine API
Introduction
How To Use
Building and Registering RuleExecutionSets
Using Stateful and Stateless RuleSessions
References
7. The Rule IDE (Eclipse)
Features Outline
Creating a Rule Project
Creating a New Rule and Wizards
Textual Rule Editor
The Guided Editor (Rule GUI)
Drools Views
The Working Memory View
The Agenda View
The Global Data View
The Audit View
Domain Specific Languages
Editing languages
The Rete View
Large DRL Files
Debugging Rules
Creating Breakpoints
Debugging Rules
8. Examples
Getting the Examples
Hello World
State Example
Understanding the State Example
Fibonacci Example
Banking Tutorial
Pricing Rule Decision Table Example
Executing the example
The decision table
Pet Store Example
Honest Politician Example
Sudoku Example
Sudoku Overview
Running the Example
Java Source and Rules Overview
Sudoku Validator Rules (validatorSudoku.drl)
Sudoku Solving Rules (solverSudoku.drl)
Suggestions for Future Developments
Number Guess
Miss Manners and Benchmarking
Introduction
Indepth Discussion
Output Summary
Conway's Game Of Life

List of Figures

1.1. High-level View of a Rule Engine
1.2. Forward Chaining
1.3. Backward Chaining
2.1. CashFlows and Account
2.2. AccountingPeriod, CashFlows and Account
2.3. CashFlows and Account
2.4. CashFlows and Account
2.5. CashFlows and Account
2.6. CashFlows and Account
2.7. CashFlows and Account
3.1. org.drools.builder
3.2. KnowledgeBuilder
3.3. KnowledgeBuilderFactory
3.4. KnowledgePackage
3.5. KnowledgeBase
3.6. KnowledgeBaseFactory
3.7. KnowledgeAgent
3.8. KnowledgeAgentFactory
3.9. StatefulKnowledgeSession
3.10. WorkingMemoryEntryPoint
3.11. WorkingMemory
3.12. QueryResults
3.13. QueryResultsRow
3.14. KnowledgeRuntime
3.15. StatefulRuleSession
3.16. AgendaFilters
3.17. Two Phase Execution
3.18. Agenda
3.19. AgendaGroup
3.20. ActivationGroup
3.21. RuleFlowGroup
3.22. KnowledgeRuntimeEventManager
3.23. WorkingMemoryEventManager
3.24. KnowlegeRuntimeEvent
3.25. KnowledgeRuntimeLoggerFactory
3.26. StatelessKnowledgeSession
3.27. PipelineFactory
3.28. CommandExecutor
3.29. ExecutionResults
3.30. Pipeline ResultHandler
3.31. MarshallerFactory
4.1. Single line comment
4.2. Multi-line comment
4.3. Error Message Format
4.4. package
4.5. import
4.6. global
4.7. function
4.8. meta_data
4.9. type_declaration
4.10. rule
4.11. rule attributes
4.12. Left Hand Side
4.13. Pattern Entity Relationship Diagram
4.14. Pattern
4.15. Constraints
4.16. Constraint
4.17. constraintGroup
4.18. fieldConstraint
4.19. restriction
4.20. literal
4.21. qualifiedIdentifier
4.22. variable
4.23. returnValue
4.24. singleValueRestriction
4.25. Operators
4.26. literalRestriction
4.27. variableRestriction
4.28. returnValueRestriction
4.29. compoundValueRestriction
4.30. multiRestriction
4.31. restrictionGroup
4.32. Inline Eval Expression
4.33. prefixAnd
4.34. infixAnd
4.35. prefixOr
4.36. infixOr
4.37. eval
4.38. not
4.39. exists
4.40. forall
4.41. from
4.42. collect
4.43. accumulate
4.44. query
7.1. Overview
7.2. New rule project scaffolding
7.3. New rule project result
7.4. The wizard menu
7.5. New rule wizard
7.6. The rule editor in action
7.7. The rule outline view
7.8. The guided editor
7.9. The Domain Specific Language editor
7.10. Language Mapping editor dialog
7.11. Debugging
7.12. Debug as Drools Application
7.13. Debug as Drools Application Configuration
7.14. Debugging
8.1. Hello World: fireAllRules Agenda View
8.2. Hello World: rule "Hello World" Agenda View
8.3. Hello World: Audit View
8.4. Salience State Example Audit View
8.5. State Example Agenda View
8.6. Fibonacci Example: "Recurse" Audit View 1
8.7. Fibonacci Example: "Recurse" Agenda View 1
8.8. Fibonacci Example: "Recurse" Agenda View 2
8.9. Fibonacci Example: "Bootstrap" Audit View
8.10. Decision table configuration
8.11. Base price calculation
8.12. Discount calculation
8.13. PetStore Demo just after Launch
8.14. PetStore Demo with Products Selected
8.15. Do we want to buy a fish tank?
8.16. Petstore Demo after all rules have fired.
8.17. Honest Politician Example Audit View
8.18. RuleFlow for the NumberGuess Example
8.19. Properties for the Number Guess Rule Flow
8.20. Edit Constraints for the "Guess Correct" Node
8.21. Constraint Editor for the "Guess Correct" Node: value too high
8.22. Miss Manners' Guests
8.23. Manners Activity Diagram
8.24. Rete Diagram
8.25. Conway's Game of Life: Starting a new game
8.26. Conway's Game of Life: A running game
8.27. Conway's Game of Life: rule flow "Generation"

List of Tables

2.1.
2.2.
2.3.
5.1. Keywords

List of Examples

3.1. Creating a new KnowledgeBuilder
3.2. Creating a new KnowledgeBuilder with a custom ClassLoader
3.3. Adding DRL Resources
3.4. Validating
3.5. Getting the KnowledgePackages
3.6. Putting it all together
3.7. XML Schema for ChangeSet XML (not normative)
3.8. Simple ChangeSet XML
3.9. Loading the ChangeSet XML
3.10. ChangeSet XML with resource configuration
3.11. ChangeSet XML which adds a directory's contents
3.12. Creating a new KnowledgeBase
3.13. Creating a new KnowledgeBase with a custom ClassLoader
3.14. Add KnowledgePackages to a KnowledgeBase
3.15. Writing the KnowledgePackage to an OutputStream
3.16. Reading the KnowledgePackage from an InputStream
3.17. Creating the KnowledgeAgent
3.18. Writing the KnowledgePackage to an OutputStream
3.19. Starting the Scanning and Notification Services
3.20. Changing the Scanning Intervals
3.21. Using an existing KnowledgeBase
3.22. ChangeSet XML which adds a directories contents
3.23. Change the Scanning Behavior
3.24. Creating a new KnowledgeBase
3.25. Create a StatefulKnowledgeSession from a KnowledgeBase
3.26. Simple Query Example
3.27. Adding an AgendaEventListener
3.28. Creating a new KnowledgeBuilder
3.29. FileLogger
3.30. Simple StatelessKnowledgeSession execution with a Collection
3.31. Simple StatelessKnowledgeSession execution with InsertElements Command
3.32. Session scoped global
3.33. Out identifiers
3.34. StatefulKnowledgeSessionPipeline
3.35. StageExceptionHandler
3.36. StageExceptionHandler
3.37. Constructing a pipeline
3.38. Using JMS with Pipeline
3.39. XStream FromXML transformer stage
3.40. XStream ToXML transformer stage
3.41. JAXB XSD Generation into the KnowlegeBuilder
3.42. JAXB From XML transformer stage
3.43. JAXB to XML transformer stage
3.44. Smooks FromSource transformer stage
3.45. Smooks ToSource transformer stage
3.46. JXLS transformer stage
3.47. JMS Messenger stage
3.48. Insert Command
3.49. InsertElements Command
3.50. BatchExecution Command
3.51. Simple BatchExecution XML
3.52. Simple ExecutionResults XML
3.53. Pipeline for CommandExecutor
3.54. Simple Pipeline ResultHandler
3.55. Using a Pipeline
3.56. BatchExecution Marshalled to XML
3.57. ExecutionResults Marshalled to XML
3.58. Root XML element
3.59. Insert
3.60. Insert with Out Identifier Command
3.61. Insert Elements command
3.62. Insert Elements command
3.63. Set Global Command
3.64. Get Global Command
3.65. Query Command
3.66. Start Process Command
3.67. Signal Event Command
3.68. Complete Work Item Command
3.69. Abort Work Item Command
3.70. Simple Marshaller Example
3.71. IdentityMarshallingStrategy
3.72. IdentityMarshallingStrategy with Acceptor
3.73. Simple example using transactions
3.74. Loading a StatefulKnowledgeSession
3.75. Configuring JPA
3.76. Configuring JTA DataSource
3.77. JNDI properties
4.1. Rules file
4.2.
4.3.
4.4.
4.5.
4.6.
4.7.
4.8.
4.9.
4.10. Declaring a new fact type: Address
4.11. declaring a new fact type: Person
4.12. Avoiding the need to use fully qualified class names by using import
4.13. generated Java class for the previous Person fact type declaration
4.14. Using the declared types in rules
4.15. Declaring a metadata attribute
4.16. Declaring metadata attributes for fact types and attributes
4.17. Declaring metadata for an existing type
4.18. Declaring metadata using the fully qualified class name
4.19. Declaring a type in the org.drools.examples package
4.20. Handling declared fact types through the API
4.21. Rule Syntax Overview
4.22. A simple rule
4.23. Some attribute examples
4.24. Rule without a Conditional Element
4.25. Simple Pattern
4.26. Pattern with a binding variable
4.27. Constraint Group connective ','
4.28. && and || Constraint Connectives
4.29. Using parentheses to change evaluation priority
4.30. Not Equivalent connectives
4.31. Regular Expression Constraint
4.32. Regular Expression Constraint
4.33. Contains with Collections
4.34. Literal Constraint with Collections
4.35. Literal Constraint with Collections
4.36. Literal Constraint with Collections
4.37. Test with soundslike
4.38. Numeric Literal Restriction
4.39. Date Literal Restriction
4.40. String Literal Restriction
4.41. Boolean Literal Restriction
4.42. Boolean Literal Restriction
4.43. Bound Field using the operator '=='
4.44. Bound Fact using 'contains' operator
4.45. Return Value Restriction
4.46. Compound Restriction using "in"
4.47. Multi Restriction
4.48. Return Value operator
4.49. Nested Accessors
4.50. prefixAnd
4.51. implicit root prefixAnd
4.52. infixAnd
4.53. prefixOr
4.54. infixOr
4.55. or with binding
4.56. eval
4.57. No Busses
4.58. No red Busses
4.59. At least one Bus
4.60. At least one red Bus
4.61. Single Pattern Forall
4.62. Multi-Pattern Forall
4.63. Combining Forall with Not CE
4.64. A modify statement
4.65. Query People over the age of 30
4.66. Query People over the age of x, and who live in y
4.67. Query People over the age of 30
4.68. Example mapping
4.69. Example with quotes
4.70. Some more examples
4.71. Some examples as processed
4.72. Chaining DSL Expressions
4.73. A rule in XML
4.74. Detail of rule element
5.1. Interpolating cell data
5.2. Rule template file: template header
5.3. Rule template file: templates
6.1. Automatic RuleServiceProvider Registration
6.2. Registering a LocalRuleExecutionSet with the RuleAdministrator API
6.3. Specifying a DSL when registering a LocalRuleExecutionSet
6.4. Register the RuleExecutionSet
6.5. Getting the RuleRuntime
6.6. Stateful Rule
6.7. Stateless
8.1. HelloWorld: Creating the KnowledgeBase and Session
8.2. HelloWorld: Event logging and Auditing
8.3. HelloWorld example: Message Class
8.4. HelloWorld: Execution
8.5. HelloWorld: System.out in the Console window
8.6. HelloWorld: System.err in the Console window
8.7. HelloWorld: rule "Hello World"
8.8. HelloWorld: rule "Good Bye"
8.9. State Class
8.10. Salience State: Execution
8.11. Salience State: Console Output
8.12. Salience State: Rule "Bootstrap"
8.13. Salience State: Rule "A to B"
8.14. Salience State: Rule "B to C"
8.15. Salience State: Rule "B to D"
8.16. Inserting a Dynamic Fact
8.17. Setter Example with PropertyChangeSupport
8.18. Agenda Group State Example: Rule "B to C"
8.19. Agenda Group State Example: Rule "B to D"
8.20. Dynamic State Example: Rule "D to E"
8.21. Dynamic Sate Example Output
8.22. Fibonacci Class
8.23. Fibonacci Example: Console Output
8.24. Fibonacci Example: Execution
8.25. Fibonacci Example: Rule "Recurse"
8.26. Fibonacci Example: Rule "Bootstrap"
8.27. Fibonacci Example: Rule "Calculate"
8.28. Banking Tutorial: RuleRunner
8.29. Banking Tutorial : Java Example1
8.30. Banking Tutorial: Rule in Example1.drl
8.31. Banking Tutorial: Output of Example1.java
8.32. Banking Tutorial: Java Example2
8.33. Banking Tutorial: Rule in Example2.drl
8.34. Banking Tutorial: Output of Example2.java
8.35. Banking Tutorial: Example3.java
8.36. Banking Tutorial: Rule in Example3.drl
8.37. Banking Tutorial: Output of Example3.java
8.38. Banking Tutorial: Class Cashflow
8.39. Banking Tutorial: Example4.java
8.40. Banking Tutorial: Class SimpleDate
8.41. Banking Tutorial: Rule in Example4.drl
8.42. Banking Tutorial: Output of Example4.java
8.43. Banking Tutorial: Class TypedCashflow
8.44. Banking Tutorial: Example5.java
8.45. Banking Tutorial: Rule in Example5.drl
8.46. Banking Tutorial: Output of Example5.java
8.47. Banking Tutorial: Class Account
8.48. Banking Tutorial: Class AllocatedCashflow
8.49. Banking Tutorial: Example5.java
8.50. Banking Tutorial: Rule in Example6.drl
8.51. Banking Tutorial: Output of Example6.java
8.52. Creating the PetStore RuleBase in PetStore.main
8.53. Firing the Rules - extract from CheckoutCallBack.checkout()
8.54. Package, Imports, Globals and Dialect: extract from PetStore.drl
8.55. Java Functions in the Rules: extract from PetStore.drl
8.56. Putting items into working memory: extract from PetStore.drl
8.57. Show Items in the GUI - extract from PetStore.drl
8.58. Evaluate Agenda Group: extract from PetStore.drl
8.59. Doing the Checkout - extract (6) from PetStore.drl
8.60. Checkout Rules: extract from PetStore.drl
8.61. Console (System.out) from running the PetStore GUI
8.62. Class Politician
8.63. Honest Politician: Execution
8.64. Honest Politician: Console Output
8.65. Honest Politician: Rule "We have an honest politician"
8.66. Honest Politician: Rule "Hope Lives"
8.67. Honest Politician: Rule "Corrupt the Honest"
8.68. Honest Politician: Rule "Hope is Dead"
8.69. Creating the Number Guess RuleBase: NumberGuessExample.main() - part 1
8.70. Starting the RuleFlow: NumberGuessExample.main() - part 2
8.71. A Rule firing only at a specific point in the Rule Flow: NumberGuess.drl
8.72. Example Console output where the Number Guess Example beat the human!
8.73. Conway's Game of Life: Register Cell Neighbour relations
8.74. Conway's Game of Life: Evaluate Cells with state changes
8.75. Conway's Game of Life: Apply the state changes
8.76. Conway's Game of Life: Evaluate cells with state changes