80.2. Stateful KIE sessions
A stateful KIE session is a session that uses inference to make iterative changes to facts over time. In a stateful KIE session, data from a previous invocation of the KIE session (the previous session state) is retained between session invocations, whereas in a stateless KIE session, that data is discarded.
Ensure that you call the dispose()
method after running a stateful KIE session so that no memory leaks occur between session invocations.
Stateful KIE sessions are commonly used for the following use cases:
- Monitoring, such as monitoring a stock market and automating the buying process
- Diagnostics, such as running fault-finding processes or medical diagnostic processes
- Logistics, such as parcel tracking and delivery provisioning
- Ensuring compliance, such as verifying the legality of market trades
For example, consider the following fire alarm data model and sample DRL rules:
Data model for sprinklers and fire alarm
public class Room { private String name; // Getter and setter methods } public class Sprinkler { private Room room; private boolean on; // Getter and setter methods } public class Fire { private Room room; // Getter and setter methods } public class Alarm { }
Sample DRL rule set for activating sprinklers and alarm
rule "When there is a fire turn on the sprinkler" when Fire($room : room) $sprinkler : Sprinkler(room == $room, on == false) then modify($sprinkler) { setOn(true) }; System.out.println("Turn on the sprinkler for room "+$room.getName()); end rule "Raise the alarm when we have one or more fires" when exists Fire() then insert( new Alarm() ); System.out.println( "Raise the alarm" ); end rule "Cancel the alarm when all the fires have gone" when not Fire() $alarm : Alarm() then delete( $alarm ); System.out.println( "Cancel the alarm" ); end rule "Status output when things are ok" when not Alarm() not Sprinkler( on == true ) then System.out.println( "Everything is ok" ); end
For the When there is a fire turn on the sprinkler
rule, when a fire occurs, the instances of the Fire
class are created for that room and inserted into the KIE session. The rule adds a constraint for the specific room
matched in the Fire
instance so that only the sprinkler for that room is checked. When this rule is executed, the sprinkler activates. The other sample rules determine when the alarm is activated or deactivated accordingly.
Whereas a stateless KIE session relies on standard Java syntax to modify a field, a stateful KIE session relies on the modify
statement in rules to notify the decision engine of changes. The decision engine then reasons over the changes and assesses impact on subsequent rule executions. This process is part of the decision engine ability to use inference and truth maintenance and is essential in stateful KIE sessions.
In this example, the sample rules and all other files in the ~/resources
folder of the Red Hat Decision Manager project are built with the following code:
Create the KIE container
KieServices kieServices = KieServices.Factory.get(); KieContainer kContainer = kieServices.getKieClasspathContainer();
This code compiles all the rule files found on the class path and adds the result of this compilation, a KieModule
object, in the KieContainer
.
Finally, the KieSession
object is instantiated from the KieContainer
and is executed against specified data:
Instantiate the stateful KIE session and enter data
KieSession ksession = kContainer.newKieSession(); String[] names = new String[]{"kitchen", "bedroom", "office", "livingroom"}; Map<String,Room> name2room = new HashMap<String,Room>(); for( String name: names ){ Room room = new Room( name ); name2room.put( name, room ); ksession.insert( room ); Sprinkler sprinkler = new Sprinkler( room ); ksession.insert( sprinkler ); } ksession.fireAllRules();
Console output
> Everything is ok
With the data added, the decision engine completes all pattern matching but no rules have been executed, so the configured verification message appears. As new data triggers rule conditions, the decision engine executes rules to activate the alarm and later to cancel the alarm that has been activated:
Enter new data to trigger rules
Fire kitchenFire = new Fire( name2room.get( "kitchen" ) ); Fire officeFire = new Fire( name2room.get( "office" ) ); FactHandle kitchenFireHandle = ksession.insert( kitchenFire ); FactHandle officeFireHandle = ksession.insert( officeFire ); ksession.fireAllRules();
Console output
> Raise the alarm > Turn on the sprinkler for room kitchen > Turn on the sprinkler for room office
ksession.delete( kitchenFireHandle ); ksession.delete( officeFireHandle ); ksession.fireAllRules();
Console output
> Cancel the alarm > Turn off the sprinkler for room office > Turn off the sprinkler for room kitchen > Everything is ok
In this case, a reference is kept for the returned FactHandle
object. A fact handle is an internal engine reference to the inserted instance and enables instances to be retracted or modified later.
As this example illustrates, the data and results from previous stateful KIE sessions (the activated alarm) affect the invocation of subsequent sessions (alarm cancellation).