org.drools.jsr94.rules
Class StatefulRuleSessionImpl

java.lang.Object
  extended byorg.drools.jsr94.rules.RuleSessionImpl
      extended byorg.drools.jsr94.rules.StatefulRuleSessionImpl
All Implemented Interfaces:
RuleSession, Serializable, StatefulRuleSession

public class StatefulRuleSessionImpl
extends RuleSessionImpl
implements StatefulRuleSession

The Drools implementation of the StatefulRuleSession interface which is a representation of a stateful rules engine session. A stateful rules engine session exposes a stateful rule execution API to an underlying rules engine. The session allows arbitrary objects to be added and removed to and from the rule session state. Additionally, objects currently part of the rule session state may be updated.

There are inherently side-effects to adding objects to the rule session state. The execution of a RuleExecutionSet can add, remove and update objects in the rule session state. The objects in the rule session state are therefore dependent on the rules within the RuleExecutionSet as well as the rule engine vendor's specific rule engine behavior.

Handle instances are used by the rule engine vendor to track Objects added to the rule session state. This allows multiple instances of equivalent Objects to be added to the session state and identified, even after serialization.

Author:
N. Alex Rupp (n_alex codehaus.org), thomas diesler
See Also:
StatefulRuleSession, Serialized Form

Constructor Summary
(package private) StatefulRuleSessionImpl(String bindUri, Map properties)
          Gets the RuleExecutionSet for this URI and associates it with a RuleBase.
 
Method Summary
 Handle addObject(Object object)
          Adds a given object to the rule session state of this rule session.
 List addObjects(List objList)
          Adds a List of Objects to the rule session state of this rule session.
protected  void applyFilter(List objects, ObjectFilter objectFilter)
          Applies the given ObjectFilter to the List of Objects, removing all Objects from the given List that do not pass the filter.
protected  void checkRuleSessionValidity()
          Ensures this RuleSession is not in an illegal rule session state.
 boolean containsObject(Handle objectHandle)
          Returns true if the given object is contained within rulesession state of this rule session.
 void executeRules()
          Executes the rules in the bound rule execution set using the objects present in the rule session state.
 List getHandles()
          Returns a List of the Handles being used for object identity.
 Object getObject(Handle handle)
           
 List getObjects()
          Returns a List of all objects in the rule session state of this rule session.
 List getObjects(ObjectFilter filter)
          Returns a List over the objects in rule session state of this rule session.
protected  Map getProperties()
          Returns the additional properties used to create this RuleSession.
protected  RuleExecutionSetImpl getRuleExecutionSet()
          Returns the Drools RuleExecutionSet associated with this RuleSession.
 RuleExecutionSetMetadata getRuleExecutionSetMetadata()
          Returns the meta data for the rule execution set bound to this rule session.
 int getType()
          Returns the type identifier for this RuleSession.
protected  WorkingMemory getWorkingMemory()
          Returns the Drools WorkingMemory associated with this RuleSession.
protected  void initWorkingMemory()
          Initialize this RuleSession with a new WorkingMemory.
protected  WorkingMemory newWorkingMemory()
          Creates a new WorkingMemory for this RuleSession.
 void release()
          Releases all resources used by this rule session.
 void removeObject(Handle handleObject)
          Removes a given object from the rule session state of this rule session.
 void reset()
          Resets this rule session.
protected  void setProperties(Map properties)
          Sets additional properties used to create this RuleSession.
protected  void setRuleExecutionSet(RuleExecutionSetImpl ruleSet)
          Sets the Drools RuleExecutionSet associated with this RuleSession.
protected  void setWorkingMemory(WorkingMemory workingMemory)
          Sets the Drools WorkingMemory associated with this RuleSession.
 void updateObject(Handle objectHandle, Object newObject)
          Notifies the rules engine that a given object in the rule session state has changed.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.rules.StatefulRuleSession
reset
 
Methods inherited from interface javax.rules.RuleSession
getRuleExecutionSetMetadata, getType, release
 

Constructor Detail

StatefulRuleSessionImpl

StatefulRuleSessionImpl(String bindUri,
                        Map properties)
                  throws RuleExecutionSetNotFoundException
Gets the RuleExecutionSet for this URI and associates it with a RuleBase.

Parameters:
bindUri - the URI the RuleExecutionSet has been bound to
properties - additional properties used to create the RuleSession implementation.
Throws:
RuleExecutionSetNotFoundException - if there is no rule set under the given URI
Method Detail

containsObject

public boolean containsObject(Handle objectHandle)
Returns true if the given object is contained within rulesession state of this rule session.

Specified by:
containsObject in interface StatefulRuleSession
Parameters:
objectHandle - the handle to the target object.
Returns:
true if the given object is contained within the rule session state of this rule session.

addObject

public Handle addObject(Object object)
                 throws InvalidRuleSessionException
Adds a given object to the rule session state of this rule session. The argument to this method is Object because in the non-managed env. not all objects should have to implement Serializable. If the RuleSession is Serializable and it contains non-serializable fields a runtime exception will be thrown.

Specified by:
addObject in interface StatefulRuleSession
Parameters:
object - the object to be added.
Returns:
the Handle for the newly added Object
Throws:
InvalidRuleSessionException - on illegal rule session state.

addObjects

public List addObjects(List objList)
                throws InvalidRuleSessionException
Adds a List of Objects to the rule session state of this rule session.

Specified by:
addObjects in interface StatefulRuleSession
Parameters:
objList - the objects to be added.
Returns:
a List of Handles, one for each added Object. The List must be ordered in the same order as the input objList.
Throws:
InvalidRuleSessionException - on illegal rule session state.

updateObject

public void updateObject(Handle objectHandle,
                         Object newObject)
                  throws InvalidRuleSessionException,
                         InvalidHandleException
Notifies the rules engine that a given object in the rule session state has changed.

The semantics of this call are equivalent to calling removeObject followed by addObject. The original Handle is rebound to the new value for the Object however.

Specified by:
updateObject in interface StatefulRuleSession
Parameters:
objectHandle - the handle to the original object.
newObject - the new object to bind to the handle.
Throws:
InvalidRuleSessionException - on illegal rule session state.
InvalidHandleException - if the input Handle is no longer valid

removeObject

public void removeObject(Handle handleObject)
                  throws InvalidRuleSessionException,
                         InvalidHandleException
Removes a given object from the rule session state of this rule session.

Specified by:
removeObject in interface StatefulRuleSession
Parameters:
handleObject - the handle to the object to be removed from the rule session state.
Throws:
InvalidRuleSessionException - on illegal rule session state.
InvalidHandleException - if the input Handle is no longer valid

getObjects

public List getObjects()
                throws InvalidRuleSessionException
Returns a List of all objects in the rule session state of this rule session. The objects should pass the default filter test of the default RuleExecutionSet filter (if present).

This may not neccessarily include all objects added by calls to addObject, and may include Objects created by side-effects. The execution of a RuleExecutionSet can add, remove and update objects as part of the rule session state. Therefore the rule session state is dependent on the rules that are part of the executed RuleExecutionSet as well as the rule vendor's specific rule engine behavior.

Specified by:
getObjects in interface StatefulRuleSession
Returns:
a List of all objects part of the rule session state.
Throws:
InvalidRuleSessionException - on illegal rule session state.

getObjects

public List getObjects(ObjectFilter filter)
                throws InvalidRuleSessionException
Returns a List over the objects in rule session state of this rule session. The objects should pass the filter test on the specified ObjectFilter.

This may not neccessarily include all objects added by calls to addObject, and may include Objects created by side-effects. The execution of a RuleExecutionSet can add, remove and update objects as part of the rule session state. Therefore the rule session state is dependent on the rules that are part of the executed RuleExecutionSet as well as the rule vendor's specific rule engine behavior.

Specified by:
getObjects in interface StatefulRuleSession
Parameters:
filter - the object filter.
Returns:
a List of all the objects in the rule session state of this rule session based upon the given object filter.
Throws:
InvalidRuleSessionException - on illegal rule session state.

executeRules

public void executeRules()
                  throws InvalidRuleSessionException
Executes the rules in the bound rule execution set using the objects present in the rule session state. This will typically modify the rule session state - and may add, remove or update Objects bound to Handles.

Specified by:
executeRules in interface StatefulRuleSession
Throws:
InvalidRuleSessionException - on illegal rule session state.

getObject

public Object getObject(Handle handle)
                 throws InvalidRuleSessionException,
                        InvalidHandleException
Specified by:
getObject in interface StatefulRuleSession
Throws:
InvalidRuleSessionException
InvalidHandleException
See Also:
StatefulRuleSessionImpl

getHandles

public List getHandles()
Returns a List of the Handles being used for object identity.

Specified by:
getHandles in interface StatefulRuleSession
Returns:
a List of Handles present in the currect state of the rule session.

initWorkingMemory

protected void initWorkingMemory()
Initialize this RuleSession with a new WorkingMemory.

See Also:
RuleSessionImpl.newWorkingMemory()

newWorkingMemory

protected WorkingMemory newWorkingMemory()
Creates a new WorkingMemory for this RuleSession. All properties set prior to calling this method are added as application data to the new WorkingMemory. The created WorkingMemory uses the default conflict resolution strategy.

Returns:
the new WorkingMemory.
See Also:
RuleSessionImpl.setProperties(Map), WorkingMemory.setApplicationData(String, Object), DefaultConflictResolver

setProperties

protected void setProperties(Map properties)
Sets additional properties used to create this RuleSession.

Parameters:
properties - additional properties used to create the RuleSession implementation.

getProperties

protected Map getProperties()
Returns the additional properties used to create this RuleSession.

Returns:
the additional properties used to create this RuleSession.

setWorkingMemory

protected void setWorkingMemory(WorkingMemory workingMemory)
Sets the Drools WorkingMemory associated with this RuleSession.

Parameters:
workingMemory - the WorkingMemory to associate with this RuleSession.

getWorkingMemory

protected WorkingMemory getWorkingMemory()
Returns the Drools WorkingMemory associated with this RuleSession.

Returns:
the Drools WorkingMemory to associate with this RuleSession.

setRuleExecutionSet

protected void setRuleExecutionSet(RuleExecutionSetImpl ruleSet)
Sets the Drools RuleExecutionSet associated with this RuleSession.

Parameters:
ruleSet - the Drools RuleExecutionSet to associate with this RuleSession.

getRuleExecutionSet

protected RuleExecutionSetImpl getRuleExecutionSet()
Returns the Drools RuleExecutionSet associated with this RuleSession.

Returns:
the Drools RuleExecutionSet associated with this RuleSession.

checkRuleSessionValidity

protected void checkRuleSessionValidity()
                                 throws InvalidRuleSessionException
Ensures this RuleSession is not in an illegal rule session state.

Throws:
InvalidRuleSessionException - on illegal rule session state.

applyFilter

protected void applyFilter(List objects,
                           ObjectFilter objectFilter)
Applies the given ObjectFilter to the List of Objects, removing all Objects from the given List that do not pass the filter.

Parameters:
objects - List of Objects to be filtered
objectFilter - the ObjectFilter to be applied

getRuleExecutionSetMetadata

public RuleExecutionSetMetadata getRuleExecutionSetMetadata()
Returns the meta data for the rule execution set bound to this rule session.

Specified by:
getRuleExecutionSetMetadata in interface RuleSession
Returns:
the RuleExecutionSetMetaData bound to this rule session.

getType

public int getType()
            throws InvalidRuleSessionException
Returns the type identifier for this RuleSession. The type identifiers are defined in the RuleRuntime interface.

Specified by:
getType in interface RuleSession
Returns:
the type identifier for this RuleSession
Throws:
InvalidRuleSessionException - on illegal rule session state.
See Also:
RuleRuntime.STATEFUL_SESSION_TYPE, RuleRuntime.STATELESS_SESSION_TYPE

release

public void release()
Releases all resources used by this rule session. This method renders this rule session unusable until it is reacquired through the RuleRuntime.

Specified by:
release in interface RuleSession

reset

public void reset()
Resets this rule session. Calling this method will bring the rule session state to its initial state for this rule session and will reset any other state associated with this rule session.

A reset will not reset the state on the default object filter for a RuleExecutionSet.



Copyright © 2001-2004 The Codehaus. All Rights Reserved.