All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.drools.runtime.StatefulKnowledgeSession Maven / Gradle / Ivy

Go to download

The Drools and jBPM public API which is backwards compatible between releases.

There is a newer version: 6.5.0.Final
Show newest version
/*
 * Copyright 2010 JBoss Inc
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.drools.runtime;

import org.drools.runtime.process.StatefulProcessSession;
import org.drools.runtime.rule.StatefulRuleSession;

/**
 * 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.newStatefulKnowledgeSession();
 * 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.newStatefulKnowledgeSession();
 * 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.newStatefulKnowledgeSession();
 * 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 org.drools.core.runtime.Globals */ public interface StatefulKnowledgeSession extends StatefulRuleSession, StatefulProcessSession, CommandExecutor, KnowledgeRuntime { int getId(); /** * Releases all the current session resources, setting up the session for garbage collection. * This method must always be called after finishing using the session, or the engine * will not free the memory used by the session. */ void dispose(); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy