Package org.kie.internal.runtime

Interface StatefulKnowledgeSession

  • All Superinterfaces:
    org.kie.api.runtime.CommandExecutor, org.kie.api.runtime.rule.EntryPoint, org.kie.api.runtime.KieRuntime, org.kie.api.event.KieRuntimeEventManager, org.kie.api.runtime.KieSession, org.kie.api.event.process.ProcessEventManager, org.kie.api.runtime.process.ProcessRuntime, org.kie.api.runtime.rule.RuleRuntime, org.kie.api.event.rule.RuleRuntimeEventManager, org.kie.api.runtime.process.StatefulProcessSession, org.kie.api.runtime.rule.StatefulRuleSession
    public interface StatefulKnowledgeSession
extends org.kie.api.runtime.KieSession, org.kie.api.runtime.KieRuntime
    StatefulKnowledgeSession is the most common way to interact with the engine. A StatefulKnowledgeSession allows the application to establish an iterative conversation with the engine, where the state of the session is kept across invocations. The reasoning process may be triggered multiple times for the same set of data. After the application finishes using the session, though, it must call the dispose() method in order to free the resources and used memory.

    Simple example showing a stateful session executing rules for a given collection of java objects. 

     KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
 kbuilder.add( ResourceFactory.newFileSystemResource( fileName ), ResourceType.DRL );
 assertFalse( kbuilder.hasErrors() );
 if (kbuilder.hasErrors() ) {
     System.out.println( kbuilder.getErrors() );
 }
 KnowledgeBase kbase = KnowledgeBaseFactory.newKnowledgeBase();
 kbase.addKnowledgePackages( kbuilder.getKnowledgePackages() );

 StatefulKnowledgeSession ksession = kbase.newKieSession();
 for( Object fact : facts ) {
     ksession.insert( fact );
 }
 ksession.fireAllRules();
 ksession.dispose();

    Simple example showing a stateful session executing processes. 

     KnowledgeBuilder kbuilder = KnowledgeBuilderFactory.newKnowledgeBuilder();
 kbuilder.add( ResourceFactory.newFileSystemResource( fileName ), ResourceType.BPMN2 );
 KnowledgeBase kbase = kbuilder.newKnowledgeBase();
 StatefulKnowledgeSession ksession = kbase.newKieSession();
 ksession.startProcess("com.sample.processid");
 ksession.signalEvent("SomeEvent", null);
 ksession.startProcess("com.sample.processid");
 ksession.dispose();

    StatefulKnowledgeSessions support globals. Globals are used to pass information into the engine (like data or service callbacks that can be used in your rules and processes), but they should not be used to reason over. If you need to reason over your data, make sure you insert it as a fact, not a global.

    Globals are shared among ALL your rules and processes, so be especially careful of (and avoid as much as possible) mutable globals. Also, it is a good practice to set your globals before inserting your facts or starting your processes. Rules engines evaluate rules at fact insertion time, and so, if you are using a global to constraint a fact pattern, and the global is not set, you may receive a NullPointerException.

    Globals can be resolved in two ways. The StatefulKnowledgeSession supports getGlobals() which returns the internal Globals, which itself can take a delegate. Calling of setGlobal(String, Object) will set the global on an internal Collection. Identifiers in this internal Collection will have priority over the externally supplied Globals delegate. If an identifier cannot be found in the internal Collection, it will then check the externally supplied Globals delegate, if one has been set.

    Code snippet for setting a global:

     StatefulKnowledgeSession ksession = kbase.newKieSession();
 ksession.setGlobal( "hbnSession", hibernateSession ); // sets a global hibernate session, that can be used for DB interactions in the rules.
 for( Object fact : facts ) {
     ksession.insert( fact );
 }
 ksession.fireAllRules(); // this will now execute and will be able to resolve the "hbnSession" identifier.
 ksession.dispose();

    Like StatelessKnowledgeSession this also implements CommandExecutor which can be used to script a StatefulKnowledgeSession. See CommandExecutor for more details.

    See Also:
    Globals

    • Nested Class Summary

      • Nested classes/interfaces inherited from interface org.kie.api.runtime.KieSession

        org.kie.api.runtime.KieSession.AtomicAction

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      org.kie.api.KieBase getKieBase()  

      • Methods inherited from interface org.kie.api.runtime.CommandExecutor

        execute

      • Methods inherited from interface org.kie.api.runtime.rule.EntryPoint

        delete, delete, getEntryPointId, getFactCount, getFactHandle, getFactHandles, getFactHandles, getObject, getObjects, getObjects, insert, retract, update, update

      • Methods inherited from interface org.kie.api.runtime.KieRuntime

        getCalendars, getChannels, getEnvironment, getGlobal, getGlobals, getSessionClock, getSessionConfiguration, registerChannel, setGlobal, unregisterChannel

      • Methods inherited from interface org.kie.api.event.KieRuntimeEventManager

        getLogger

      • Methods inherited from interface org.kie.api.runtime.KieSession

        destroy, dispose, getId, getIdentifier, getKieRuntime, submit

      • Methods inherited from interface org.kie.api.event.process.ProcessEventManager

        addEventListener, getProcessEventListeners, removeEventListener

      • Methods inherited from interface org.kie.api.runtime.process.ProcessRuntime

        abortProcessInstance, createProcessInstance, getProcessInstance, getProcessInstance, getProcessInstances, getWorkItemManager, signalEvent, signalEvent, startProcess, startProcess, startProcess, startProcess, startProcessFromNodeIds, startProcessInstance

      • Methods inherited from interface org.kie.api.runtime.rule.RuleRuntime

        getAgenda, getEntryPoint, getEntryPoints, getQueryResults, halt, openLiveQuery

      • Methods inherited from interface org.kie.api.event.rule.RuleRuntimeEventManager

        addEventListener, addEventListener, getAgendaEventListeners, getRuleRuntimeEventListeners, removeEventListener, removeEventListener

      • Methods inherited from interface org.kie.api.runtime.rule.StatefulRuleSession

        fireAllRules, fireAllRules, fireAllRules, fireAllRules, fireUntilHalt, fireUntilHalt

    • Method Detail

      • getKieBase

        org.kie.api.KieBase getKieBase()
        Specified by:
        getKieBase in interface org.kie.api.runtime.KieRuntime