Class IlrContext
- java.lang.Object
-
- ilog.rules.engine.IlrContext
-
- All Implemented Interfaces:
- java.io.Serializable
public class IlrContext extends java.lang.Object implements java.io.Serializable
IlrContext
is the base class of all the execution contexts. Rules can be executed only within an execution context.Overview
In IBM Decision server, the rule engine is an instance of
IlrContext
, the rule engine is simply a Java object.An
IlrContext
instance is always attached to anIlrRuleset
. If the context is created without a ruleset passed as an argument, it creates its own ruleset.An
IlrContext
instance contains all the methods required to control the rule engine.IlrRuleset
is responsible for rule management,IlrContext
is responsible for rule execution.Deprecations and warnings
Since version 5.0, the derivation of
IlrContext
has been deprecated. You should use ruleset variables to add new fields to the execution context.An execution context is serializable.
Warning: Serialized objects of this class will not be compatible with future releases. The current serialization support is appropriate for short term storage or RMI between applications running the same version of IBM Decision Server.
-
-
Field Summary
Fields Modifier and Type Field and Description static java.lang.String
firedRulesCountConstant
Deprecated.use insteadIlrPropertyNames.FIRED_RULES_COUNT
java.io.PrintWriter
out
Deprecated.As of ODM 8.0.1, the methodnote(String)
should be used
-
Constructor Summary
Constructors Constructor and Description IlrContext()
Deprecated.As of JRules 7.1, this way of constructing a context with an empty ruleset is deprecated. See other constructors for replacement.IlrContext(IlrRuleset ruleset)
Constructs anIlrContext
with anIlrRuleset
object.IlrContext(IlrRuleset ruleset, com.ibm.rules.engine.connector.DataConnectorFactory dcf)
-
Method Summary
Methods Modifier and Type Method and Description void
activatePacket(java.lang.String packet)
Deprecated.void
activateRule(IlrRule rule)
Deprecated.void
activateRules(IlrRule[] rules)
Deprecated.void
addNoteHandler(IlrNoteHandler handler)
Adds a note handler to the context.java.lang.Object
assertLogical(java.lang.Object object)
Deprecated.As of IBM Decision Server 8.0.1, truth maintenance system is deprecated.void
cleanRulesetVariables()
Resets the values of the ruleset variables: either the 'in' parameters, or the 'out' or the local variables.int
connectTool(IlrTool tool)
Connects anIlrTool
to the context.int
connectTool(IlrToolFactory toolFactory)
Connects anIlrTool
created by anIlrToolFactory
to the context.int
connectTool(IlrToolFactory toolFactory, java.lang.String name)
Connects anIlrTool
created by anIlrToolFactory
to the context.void
deactivatePacket(java.lang.String packet)
Deprecated.void
deactivateRule(IlrRule rule)
Deprecated.void
deactivateRules(IlrRule[] rules)
Deprecated.void
disconnectTool(int toolID)
Disconnects a connectedIlrTool
.void
disconnectTools()
Disconnects all connectedIlrTool
.void
end()
Prepares this context for garbage collection.void
endCurrentTask()
Ends the context's current task by executing its potential final actions and declaring it as Completed.java.util.Enumeration
enumerateInstances()
Enumerates all the rule instances currently in the agenda of the context, without changing the contents of the agenda.java.util.Enumeration
enumerateObjects()
Enumerates all the objects in working memory of the context without any discrimination on their types.IlrParameterMap
execute()
Executes the ruleflow defined in the context's ruleset.
IlrParameterMap
execute(java.lang.String name)
Executes the task passed as the argument.void
executeInitialRule()
Deprecated.java.lang.Object
executeMain(java.lang.Object arg)
Invokes theilrmain
function with an argument.java.lang.Object
executeMain(java.lang.String pkgName, java.lang.Object arg)
Invokes theilrmain
function of the specified package with an argument.IlrParameterMap
executeTask()
Provides a step-by-step execution of the ruleflow.
int
fireAllRules()
Fires all the rules in the agenda.int
fireAllRules(IlrAgendaFilter filter)
Fires all the rules in the agenda using an agenda filter.IlrRuleInstance
fireRule()
Fires the rule in the agenda that has the highest priority.IlrRuleInstance
fireRule(IlrAgendaFilter filter)
Fires the next rule instance in the agenda that passes the filter.int
fireRules(IlrRule[] rules)
Adds the rules passed as its argument to the context, fires all the rules in the agenda, and removes the rules that were passed as its argument.IlrRule[]
getActivatedRules()
Deprecated.int
getConnectedToolNumber()
Gives the number of connectedIlrTool
(s) to the context.IlrTask
getCurrentTask()
Returns the task that is currently executing or the task that is in a suspended state in the ruleflow.
static IlrNoteHandler
getDefaultNoteHandler()
Returns the default note handler.IlrEvent
getEvent(java.lang.Object object)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.IlrExceptionHandler
getExceptionHandler()
Gets the exception handler of this execution context.IlrRuleInstance
getFirstInstance()
Gets the first rule instance of the agenda.IlrTask
getMainTask()
Returns the task defined as the main task in the context's ruleset ruleflow.
java.lang.Object[]
getObjects(IlrClass clazz)
Gets all the objects in working memory that are instances of the passed XOM class.java.lang.Object
getParameterValue(java.lang.String name)
Gets the value of the ruleset parameter.IlrParameterMap
getReturnValues()
Returns the values of the "out" ruleset variables (those defined either with the "inout" or "out" modifier).
IlrRuleset
getRuleset()
Gets the ruleset to which the context is attached.IlrTask
getTask(java.lang.String name)
Returns the task defined in the ruleflow and whose name is the one passed as the parameter.
boolean
hasInstances(IlrRule rule)
Tests whether the agenda contains instances of a rule.void
insert(java.lang.Object object)
Inserts the object passed as the argument.IlrEvent
insertEvent(long timestamp, java.lang.Object object)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.IlrEvent
insertEvent(java.lang.Object object)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.java.lang.Object
insertLogical(java.lang.Object object)
Deprecated.As of IBM Decision Server 8.0.1, truth maintenance system is deprecated.java.lang.Object
invokeFunction(java.lang.String name, java.lang.Object[] arguments)
Invokes a function of the context giving its name and the argument values.boolean
isAgendaNotEmpty()
Tests whether the agenda contains at least one fireable rule instance.boolean
isCacheRuleflowData()
Tests whether or not the ruleflow data is cached whenresetRuleflow()
is called.boolean
isRuleActivated(IlrRule rule)
Deprecated.boolean
isRuleflowCompleted()
Tests whether the ruleflow execution is completed, which means that the ruleflow execution is not interrupted because of either a suspended task or a task by task execution.
boolean
isRuleSelected(IlrRule rule)
Tests whether the rule is selected to be part of the executable rules.boolean
isTaskCompleted(java.lang.String name)
Tests whether the specified task is completed.
boolean
isUsingFlow()
Returns a boolean to indicate whether a ruleflow has been defined in the context's ruleset.
long
nextTime()
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.long
nextTime(long increment)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.void
note(java.lang.String note)
Sends a note to the context's note handlers.void
refreshAgenda()
Adds in the agenda all the rule instances that have been refracted.void
removeAllInstances()
Removes all the instances currently in the agenda without firing them.void
removeAllNoteHandlers()
Removes all note handlers from the context.void
removeInstance(IlrRuleInstance instance)
Removes a particular rule instance from the agenda.void
removeInstances(IlrRule rule)
Removes all the instances of a rule currently in the agenda without firing them.void
removeNoteHandler(IlrNoteHandler handler)
Removes a note handler from the context.void
reset()
Called by Rule Studio to prepare a context for another execution.void
resetRuleflow()
Resets ruleflow execution in the context.void
retract(java.lang.Object object)
Retracts an object from working memory, if the object has been asserted.void
retractAll()
Retracts all the objects from working memory.void
retractEvent(java.lang.Object object)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.void
send(java.lang.Object object)
Throws anIlrUserActionException
exception.void
send(java.lang.String message, java.lang.Object object)
Throws anIlrUserActionException
exception using a message and an object.void
setCacheRuleflowData(boolean cache)
Sets whether or not to keep the cached ruleflow data whenresetRuleflow()
is called.void
setExceptionHandler(IlrExceptionHandler handler)
Sets the exception handler of this execution context.void
setMainTask(java.lang.String name)
Sets the ruleflow main task by giving its name.
void
setParameters(IlrParameterMap parameters)
Sets the values of the declared ruleset variables contained in the passed
IlrParameterMap
(defined either with the "in" or "inout" modifier).void
setParameterValue(java.lang.String name, java.lang.Object value)
Sets the value of the ruleset parameter.void
setRuleflowExceptionHandler(IlrExceptionHandler handler)
Sets the exception handler responsible for catching runtime exceptions thrown during the execution of a ruleflow.
void
setTime(long time)
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.long
time()
Deprecated.As of IBM Decision Server 7.5, event processing is deprecated.void
update(java.lang.Object object)
Updates an object in working memory, if the object has been asserted.void
update(java.lang.Object object, boolean refresh)
Updates an object in working memory if the object has been asserted.void
updateContext()
Updates the references to the context object.void
updateContext(boolean refresh)
Updates references to the context object to ensure that the agenda is in a consistent state with the objects referenced by this context.
-
-
-
Field Detail
-
out
public transient java.io.PrintWriter out
Deprecated. As of ODM 8.0.1, the methodnote(String)
should be usedThis field is intended to be used in rules to print errors or messages. It is initialized to aPrintWriter
which prints toSystem.out
. The destination, of course, can be changed. This field provides an easy way to redirect the printing of messages.
-
firedRulesCountConstant
public static java.lang.String firedRulesCountConstant
Deprecated. use insteadIlrPropertyNames.FIRED_RULES_COUNT
This constant is the key used in the parameter map returned by theexecute
andgetReturnValues
methods to store the number of rules fired during this execution. Its value isilog.rules.firedRulesCount
.
-
-
Constructor Detail
-
IlrContext
@Deprecated public IlrContext()
Deprecated. As of JRules 7.1, this way of constructing a context with an empty ruleset is deprecated. See other constructors for replacement.Constructs anIlrContext
with no argument. This method creates an emptyIlrRuleset
attached to the context. The ruleset can then be obtained using thegetRuleset()
method.The creation of a context, ordinarily fires the Initial Actions. Since this constructor creates its own ruleset, and the ruleset has no rules initially, then there is no Initial Actions to fire.
- See Also:
getRuleset()
-
IlrContext
public IlrContext(IlrRuleset ruleset)
Constructs anIlrContext
with anIlrRuleset
object. The ruleset must have the same context class as the created context. If not, anIlrBadContextException
is thrown.If the ruleset has an Initial Action, and if the instance being constructed is a direct instance of
IlrContext
, the action is executed. In the case that the context is derived, the user must callexecuteInitialRule()
explicitly in the body of the derived class constructor, after all the fields have been initialized.- Parameters:
ruleset
- The ruleset to which the context is attached.- See Also:
IlrBadContextException
-
IlrContext
public IlrContext(IlrRuleset ruleset, com.ibm.rules.engine.connector.DataConnectorFactory dcf)
-
-
Method Detail
-
connectTool
public int connectTool(IlrTool tool) throws IlrToolConnectionException
Connects anIlrTool
to the context. AnIlrToolConnectionException
is thrown if the connection fails.- Throws:
IlrToolConnectionException
- Parameters:
tool
- TheIlrTool
to connect.- Returns:
- the connected
IlrTool
's identifier. - See Also:
IlrTool
,IlrToolConnectionException
-
connectTool
public int connectTool(IlrToolFactory toolFactory) throws IlrToolConnectionException
Connects anIlrTool
created by anIlrToolFactory
to the context. AnIlrToolConnectionException
is thrown if the connection fails.- Throws:
IlrToolConnectionException
- Parameters:
toolFactory
- TheIlrToolFactory
used to create a newIlrTool
.- Returns:
- the connected
IlrTool
's identifier. - See Also:
IlrTool
,IlrToolConnectionException
,IlrLocalTracerToolFactory
,ilog.rules.debug.IlrBuilderToolFactory
-
connectTool
public int connectTool(IlrToolFactory toolFactory, java.lang.String name) throws IlrToolConnectionException
Connects anIlrTool
created by anIlrToolFactory
to the context. AnIlrToolConnectionException
is thrown if the connection fails.- Throws:
IlrToolConnectionException
- Parameters:
toolFactory
- TheIlrToolFactory
used to create a newIlrTool
.name
- A user context name. This name can be used by each createdIlrTool
to identify the context.- Returns:
- the connected
IlrTool
's identifier. - See Also:
IlrTool
,IlrToolConnectionException
,IlrLocalTracerToolFactory
,ilog.rules.debug.IlrBuilderToolFactory
-
getConnectedToolNumber
public int getConnectedToolNumber()
Gives the number of connectedIlrTool
(s) to the context.- Returns:
- the number of connected
IlrTool
(s).
-
disconnectTool
public void disconnectTool(int toolID)
Disconnects a connectedIlrTool
.- Parameters:
toolID
- TheIlrTool
's identifier.
-
disconnectTools
public void disconnectTools()
Disconnects all connectedIlrTool
.
-
note
public void note(java.lang.String note)
Sends a note to the context's note handlers.When a context is created, a default note handler is set (see
getDefaultNoteHandler()
. This default note handler may be removed by a call toremoveAllNoteHandlers()
. Other note handlers may be added by callingaddNoteHandler(IlrNoteHandler)
.This method is multi-thread safe at the context level, yet the note handlers that are called may not be multi-thread safe themselves.
- Since:
- JRules 7.0
- Parameters:
note
- The note.
-
addNoteHandler
public void addNoteHandler(IlrNoteHandler handler)
Adds a note handler to the context. This method is multi-thread safe.- Since:
- JRules 7.0
- Parameters:
handler
- The note handler.- See Also:
note(String)
,removeNoteHandler(IlrNoteHandler)
,removeAllNoteHandlers()
-
removeNoteHandler
public void removeNoteHandler(IlrNoteHandler handler)
Removes a note handler from the context. This method is multi-thread safe.- Since:
- JRules 7.0
- Parameters:
handler
- The note handler.- See Also:
note(String)
,addNoteHandler(IlrNoteHandler)
,removeAllNoteHandlers()
-
removeAllNoteHandlers
public void removeAllNoteHandlers()
Removes all note handlers from the context. This method is multi-thread safe. After this method, callingnote(String)
has no effect.- Since:
- JRules 7.0
- See Also:
note(String)
,addNoteHandler(IlrNoteHandler)
,removeNoteHandler(IlrNoteHandler)
,removeAllNoteHandlers()
-
getDefaultNoteHandler
public static IlrNoteHandler getDefaultNoteHandler()
Returns the default note handler. The default note handler printlns the notes to the context'sout
.- Since:
- JRules 7.0
- See Also:
note(String)
-
getRuleset
public final IlrRuleset getRuleset()
Gets the ruleset to which the context is attached.- Returns:
- the ruleset to which the context is attached.
-
end
public final void end()
Prepares this context for garbage collection. After this call, the engine will not keep any reference to this context. The context will be detached from the ruleset and will no longer be notified of modifications on the rules. The context will also disconnect all its tools and all the related resources will be released. If the application does not keep this object, it is then subject to garbage collection.
-
reset
public void reset()
Called by Rule Studio to prepare a context for another execution. When a context is debugged in Rule Studio, and when the user choosesreset
, Rule Studio calls this method to make the context ready for another run. By default, this method is defined as:public synchronized void reset() { retractAll(); cleanRulesetVariables(); resetRuleflow(); executeInitialRule(); }
A derived context class may override this method to perform additional preparations for the execution of the context.
-
send
public void send(java.lang.Object object) throws IlrUserActionException
Throws anIlrUserActionException
exception. This method is intended to be used in a rule action to exit from the firing loop. The method can catch the exception and process the result. An object is passed along with the exception. It may contain a result or the cause.- Throws:
IlrUserActionException
- Parameters:
object
- The object used to construct the exception.- See Also:
send(java.lang.String,java.lang.Object)
-
send
public void send(java.lang.String message, java.lang.Object object) throws IlrUserActionException
Throws anIlrUserActionException
exception using a message and an object.- Throws:
IlrUserActionException
- Parameters:
message
- The message used to construct the exception.object
- The object used to construct the exception.- See Also:
send(Object)
-
getExceptionHandler
public final IlrExceptionHandler getExceptionHandler()
Gets the exception handler of this execution context. At its creation, an execution context has no exception handler.- Returns:
- an exception handler, or
null
if no exception handler has been set.
-
setExceptionHandler
public void setExceptionHandler(IlrExceptionHandler handler)
Sets the exception handler of this execution context. An exception handler is an object implementingjava.io.Serializable
. Note that the exception handler mechanism is restricted to the tasks running the Rete+ algorithm. Even if set, the exception handler will not be called from a task running the Sequential algorithm or the Fastpath algorithm.- Parameters:
handler
- The new exception handler for this context. If this parameter isnull
, the context will be set without an exception handler.
-
executeInitialRule
@Deprecated public void executeInitialRule()
Deprecated.Executes the Initial Actions of the ruleset to which the context is attached, if any. If there is an Initial Action when the context is created, and if the constructed context is a direct instance ofIlrContext
, the action(s) is/are automatically executed.
-
invokeFunction
public java.lang.Object invokeFunction(java.lang.String name, java.lang.Object[] arguments) throws IlrNoSuchFunctionException
Invokes a function of the context giving its name and the argument values. The error messages are written to the standard output of the context.- Throws:
IlrNoSuchFunctionException
- in case the function is not known.- Parameters:
name
- The function name.arguments
- The argument array.- Returns:
- the result of this invocation. If the invoked function is void,
this method returns
null
.
-
executeMain
public java.lang.Object executeMain(java.lang.Object arg) throws IlrNoSuchFunctionException
Invokes theilrmain
function with an argument.- Throws:
IlrNoSuchFunctionException
- if theilrmain
is not defined.- Parameters:
arg
- The argument of the function.- Returns:
- the result of this invocation. If the invoked function is void,
this method returns
null
.
-
executeMain
public java.lang.Object executeMain(java.lang.String pkgName, java.lang.Object arg) throws IlrNoSuchFunctionException
Invokes theilrmain
function of the specified package with an argument.- Throws:
IlrNoSuchFunctionException
- if theilrmain
is not defined in this package.- Parameters:
arg
- The argument of the function.- Returns:
- the result of this invocation. If the invoked function is void,
this method returns
null
.
-
time
@Deprecated public final long time()
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Gets the time of the engine. A rule engine runs a time counter used to trigger the watchdogs and the event conditions. The time counter is driven by the application using the methods of this class.- Returns:
- the current time.
- See Also:
nextTime()
,nextTime(long)
,setTime(long)
-
nextTime
@Deprecated public final long nextTime()
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Increments the time by one unit.- Returns:
- the time of the engine after the increment has been done.
- See Also:
time()
,nextTime(long)
,setTime(long)
-
nextTime
@Deprecated public final long nextTime(long increment)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Changes the time using an increment.- Parameters:
increment
- A positive time increment.- Returns:
- the time of the engine after the increment has occurred.
- See Also:
time()
,nextTime()
,setTime(long)
-
setTime
@Deprecated public final void setTime(long time)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Sets the time of the engine. The time passed as the argument must be greater than the current time.- Parameters:
time
- The new time of the engine.- See Also:
time()
,nextTime()
,nextTime(long)
-
insert
public void insert(java.lang.Object object)
Inserts the object passed as the argument. If the object implements theIlrEvent
interface, it is inserted as an event; its timestamp is obtained by calling thetime
method specified by this interface. If the object is already in working memory, a normal update is performed.- Since:
- 4.0
- Parameters:
object
- The object to insert.
-
insertLogical
public java.lang.Object insertLogical(java.lang.Object object)
Deprecated. As of IBM Decision Server 8.0.1, truth maintenance system is deprecated.Inserts a logical object. The engine first examines the objects in working memory to find one that is equal to the object passed as the argument using theequals
method. If such an object is found, the passed object is not inserted and the object in working memory is returned. If no such object is found, the provided object is inserted and returned. In both cases, the object in working memory is stated: it is not maintained by any rule.- Parameters:
object
- The logical object to be inserted.- Returns:
- the object if no matching object has been found. If there is a matching object, it is returned.
-
assertLogical
public java.lang.Object assertLogical(java.lang.Object object)
Deprecated. As of IBM Decision Server 8.0.1, truth maintenance system is deprecated.An alias forinsertLogical(Object)
method.- Parameters:
object
- The logical object to be inserted.- Returns:
- the object if no matching object has been found. If there is a matching object, it is returned.
-
insertEvent
@Deprecated public IlrEvent insertEvent(java.lang.Object object)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Inserts an object as an event.If the object implements the
IlrEvent
interface, its timestamp is obtained by calling thetime
method specified by this interface. The method then returns the inserted object itself.If the object does not implement the
IlrEvent
interface, the current value of the context internal clock is taken for the object timestamp. This method builds an instance of theIlrDefaultEvent
class encapsulating the inserted object, and returns it.In all cases, if the event is already in working memory, a normal update is performed instead of the insert operation. Otherwise, the returned object is added to working memory.
- Parameters:
object
- The object to be inserted as an event.- Returns:
- the object inserted or updated in working memory.
- See Also:
time()
-
insertEvent
@Deprecated public IlrEvent insertEvent(long timestamp, java.lang.Object object)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Asserts an object as an event. The object must not implement theIlrEvent
interface. (If it does, the method throws anIllegalArgumentException
.) This method builds an instance of theIlrDefaultEvent
encapsulating the asserted object, taking the provided date for the object timestamp, adds the created instance to working memory, and returns it. If the event is already in working memory, a normal update is performed instead of the assert operation.- Throws:
java.lang.IllegalArgumentException
- Ifobject
implements theIlrEvent
interface.- Parameters:
timestamp
- The timestamp of the object to be asserted as an event.object
- The object to be asserted as an event.- Returns:
- The object asserted or updated in working memory.
-
retract
public void retract(java.lang.Object object)
Retracts an object from working memory, if the object has been asserted. If the object has been asserted as an event and does not implement theIlrEvent
interface, then this method must be provided with the instance ofIlrDefaultEvent
that has been created and returned upon assertion, and that can also be retrieved using thegetEvent(java.lang.Object)
method.- Parameters:
object
- The object to retract.- See Also:
retractEvent(Object)
-
retractEvent
@Deprecated public void retractEvent(java.lang.Object object)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Retracts an object from working memory, if the object has been asserted as an event. This method can be provided with objects that do not implement theIlrEvent
interface.- Parameters:
object
- The object to retract.- See Also:
retract(Object)
,getEvent(Object)
-
update
public final void update(java.lang.Object object)
Updates an object in working memory, if the object has been asserted. This method is equivalent to calling
update(Object,boolean)
with the second argument set tofalse
.- Parameters:
object
- The object to update.
-
update
public void update(java.lang.Object object, boolean refresh)
Updates an object in working memory if the object has been asserted. If the Boolean argument is
false
, this method does the same thing as the previous method. If the Boolean argument istrue
, the update will cause the agenda to be refreshed: if a rule that uses this object istrue
, a rule instance is inserted into the agenda. In this case, the rule applies as long as it can be fired.- Parameters:
object
- The object to update.refresh
- The update flag. It isfalse
for a normal update andtrue
for a looping rule behavior.
-
updateContext
public final void updateContext()
Updates the references to the context object. Calling this method is equivalent to calling
updateContext(boolean)
withfalse
as argument.
-
updateContext
public void updateContext(boolean refresh)
Updates references to the context object to ensure that the agenda is in a consistent state with the objects referenced by this context. Call this method when the following critearia are matched:- The rules of this execution context contain references to objects
accessed using this context object, that is, the
?context
variable in the rules. - The objects have been modified.
- Parameters:
refresh
- Set totrue
if a rule instance must be created for each combination of objects that satisfies a rule. This flag has the same interpretation asupdate(Object,boolean)
.
- The rules of this execution context contain references to objects
accessed using this context object, that is, the
-
retractAll
public void retractAll()
Retracts all the objects from working memory. The context becomes empty as if it had just been created (without the execution of the Initial Actions). The agenda is also emptied. The rules are not affected by this method.
-
getObjects
public final java.lang.Object[] getObjects(IlrClass clazz)
Gets all the objects in working memory that are instances of the passed XOM class. The returned objects can be direct instances of the XOM class, or instances of a sub-class of the XOM class.
- Parameters:
clazz
- The XOM class.- Returns:
- An array of objects.
-
getEvent
@Deprecated public final IlrEvent getEvent(java.lang.Object object)
Deprecated. As of IBM Decision Server 7.5, event processing is deprecated.Returns the event object in working memory if the object provided has been asserted as an event. If
object
implements theIlrEvent
interface, the returned object will be the object itself. Otherwise, the returned object will be the instance ofIlrDefaultEvent
which was created on assertion. If the object has not been asserted as an event, the method returnsnull
.- Parameters:
object
- The object to look for in working memory as an event.- Returns:
- the event object in working memory, or
null
if the object has not been asserted as an event.
-
enumerateObjects
public final java.util.Enumeration enumerateObjects()
Enumerates all the objects in working memory of the context without any discrimination on their types.
- Returns:
- an enumeration of objects.
-
isAgendaNotEmpty
public final boolean isAgendaNotEmpty()
Tests whether the agenda contains at least one fireable rule instance.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a RetePlus algorithm and a dynamic ordering.
- Returns:
true
if the agenda is not empty,false
if the agenda is empty.
-
getFirstInstance
public final IlrRuleInstance getFirstInstance()
Gets the first rule instance of the agenda. This rule instance is the one placed at the top of the agenda and is the next to be fired. The agenda is not modified.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with the RetePlus algorithm and a dynamic ordering.
- Returns:
- the first rule instance of the agenda, or
null
if the agenda is empty.
-
hasInstances
public final boolean hasInstances(IlrRule rule)
Tests whether the agenda contains instances of a rule.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Parameters:
rule
- The rule for which existence of instances is to be checked.- Returns:
true
if the agenda contains at least one instance of the rule, otherwise it returnsfalse
.
-
removeInstances
public final void removeInstances(IlrRule rule)
Removes all the instances of a rule currently in the agenda without firing them.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Parameters:
rule
- The rule for which instances are to be removed.
-
removeAllInstances
public final void removeAllInstances()
Removes all the instances currently in the agenda without firing them. The agenda will become empty.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
-
removeInstance
public final void removeInstance(IlrRuleInstance instance)
Removes a particular rule instance from the agenda.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Parameters:
instance
- The rule instance to remove from the agenda.
-
enumerateInstances
public final java.util.Enumeration enumerateInstances()
Enumerates all the rule instances currently in the agenda of the context, without changing the contents of the agenda.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Returns:
- an enumeration of rule instances.
-
refreshAgenda
public final void refreshAgenda()
Adds in the agenda all the rule instances that have been refracted. A refracted rule instance is one which has been fired or filtered, and which still evaluates to true.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
-
fireRule
public IlrRuleInstance fireRule()
Fires the rule in the agenda that has the highest priority.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Returns:
- the rule instance that was fired, or
null
if the agenda is empty.
-
fireRule
public IlrRuleInstance fireRule(IlrAgendaFilter filter)
Fires the next rule instance in the agenda that passes the filter. If the filter is
null
, then the next instance is fired. Otherwise, a rule instance is popped from the agenda, if it passes the filter, it is fired. If it does not pass the filter, it is discarded. This process loops until a rule instance is found that passes the filter or the agenda is empty.Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Returns:
- the next rule instance that was fired or
null
if the agenda is empty or no rule instance in the agenda passes the filter.
-
fireAllRules
public int fireAllRules()
Fires all the rules in the agenda.
Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Returns:
- the number of rules fired by the rule engine.
-
fireAllRules
public int fireAllRules(IlrAgendaFilter filter)
Fires all the rules in the agenda using an agenda filter. If the passed filter is
null
, then all the rule instances are fired. Otherwise, a rule instance is popped from the agenda, if it passes the filter, it is fired. If it does not pass the filter, it is discarded. This process loops until no rule instance is left in the agenda.Note: This method can be used in the following cases:
- The rules are executed without a rule task
- The rules are executed in a rule task with a default algorithm and a dynamic ordering.
- Parameters:
filter
- The agenda filter.- Returns:
- the number of rule instances fired by this call.
-
activateRule
public void activateRule(IlrRule rule)
Deprecated.Adds a rule to the context. The rule must belong to the ruleset to which this context is attached. Otherwise, this method does nothing.
If the rule is added, only the current context is affected. The contents of this context is updated accordingly.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rule
- The rule to be added.
-
activateRules
public void activateRules(IlrRule[] rules)
Deprecated.Adds rules to the context. If the context class of the added rules does not match this context or if the context already contains the specified rules, the rule are not added. If rules are added, only the current context is affected. The content of the context is updated.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rules
- The rules to be added.
-
activatePacket
public void activatePacket(java.lang.String packet)
Deprecated.Activates a rule packet.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
packet
- The packet to be activated.
-
deactivatePacket
public void deactivatePacket(java.lang.String packet)
Deprecated.Deactivates a rule packet.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
packet
- The packet to be deactivated.
-
deactivateRule
public void deactivateRule(IlrRule rule)
Deprecated.Removes a rule from the context. The rule must belong to the ruleset to which this context is attached. Otherwise, this method does nothing.
If the rule is removed, the contents of this context is updated.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rule
- The rule to be removed.
-
deactivateRules
public void deactivateRules(IlrRule[] rules)
Deprecated.Removes rules from the context. If the context class of the rules to be removed does not match this context or if the context does not contain the specified rules, the rule are not removed. If rules are removed, only the current context is affected. The content of the context is updated.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rules
- The rules to be removed.
-
isRuleActivated
public final boolean isRuleActivated(IlrRule rule)
Deprecated.Tests whether this context contains a rule.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rule
- A rule.- Returns:
true
if the context contains the rule, otherwise it returnsfalse
.
-
isRuleSelected
public final boolean isRuleSelected(IlrRule rule)
Tests whether the rule is selected to be part of the executable rules. In case there is no ruleflow, this method returns the same value as
isRuleActivated
. If there is a ruleflow, this method returnstrue
if the rule is part of the current task, else it returnsfalse
.- Parameters:
rule
- A rule.- Returns:
true
if the the rule is selected as executable rule, otherwise it returnsfalse
.
-
getActivatedRules
public final IlrRule[] getActivatedRules()
Deprecated.Returns all the rules in the context.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Returns:
- an array of
IlrRule
. The length of the array can be 0.
-
fireRules
public int fireRules(IlrRule[] rules)
Adds the rules passed as its argument to the context, fires all the rules in the agenda, and removes the rules that were passed as its argument. It returns the number of fired rules. This method is particularly useful if you know the agenda is empty and you only want specific rules to be fired.
Note: This method may not work within a ruleflow, as the rules in a ruleflow are controlled by their tasks.
- Parameters:
rules
- The rules to be fired.- Returns:
- the number of rules fired.
-
execute
public IlrParameterMap execute()
Executes the ruleflow defined in the context's ruleset. If the ruleflow is in a suspended state (its execution has been started but is hanging because one task has not completed), execution will resume from the uncompleted task, that is, "the current task".
This method calls
fireAllRules
if no ruleflow is defined in the context's ruleset.The number of fired rules is returned in the returned
IlrParameterMap
(when a ruleflow is executed, the number of rules corresponds to the total number of rules fired during the entire ruleflow execution). The value can be get in the result with the nameIlrContext.firedRulesCountConstant
. The method also returns the values of the ruleset variables whose modifier is either "out" or "inout".- Returns:
- an
IlrParameterMap
containing the "out" and "inout" ruleset variable values and the number of rules fired. - See Also:
IlrParameterMap
-
setMainTask
public void setMainTask(java.lang.String name)
Sets the ruleflow main task by giving its name. If no task with this name is defined in the context's ruleset, an
IlrUserRuntimeException
, encapsulating anIlrUndefinedTaskException
is thrown. This exception can be caught if a ruleflow exception handler has been set on the context. The task set with this method takes precedence over any task named "main" in the ruleflow.If there is no ruleflow defined in the context's ruleset, this method will be ignored.
-
getMainTask
public IlrTask getMainTask()
Returns the task defined as the main task in the context's ruleset ruleflow. The ruleflow's main task is defined as follows: - the task whose property "mainflowtask" is set to
true
, or - the task named "main", or - the task set as main by the API callsetMainTask
.- Returns:
- The ruleflow's main task.
-
setParameters
public void setParameters(IlrParameterMap parameters)
Sets the values of the declared ruleset variables contained in the passed
IlrParameterMap
(defined either with the "in" or "inout" modifier). If one of the values does not correspond to an "in" or "inout" variable in the ruleset, anIllegalArgumentException
exception is thrown.- Parameters:
parameters
- The structure containing "in" and "inout" ruleset variables with a given value.
-
setParameterValue
public void setParameterValue(java.lang.String name, java.lang.Object value)
Sets the value of the ruleset parameter. In case the parameter is not defined on the ruleset, anIllegalArgumentException
is thrown.- Parameters:
name
- The name of the parameter whose value is set.value
- The value of the ruleset parameter.
-
getParameterValue
public java.lang.Object getParameterValue(java.lang.String name)
Gets the value of the ruleset parameter. In case the parameter is not defined on the ruleset, anIllegalArgumentException
is thrown.- Parameters:
name
- The name of the parameter whose value is requested
-
cleanRulesetVariables
public void cleanRulesetVariables()
Resets the values of the ruleset variables: either the 'in' parameters, or the 'out' or the local variables.
-
getReturnValues
public IlrParameterMap getReturnValues()
Returns the values of the "out" ruleset variables (those defined either with the "inout" or "out" modifier). The returned value contains the number of fired rules stored in the variable
IlrContext.firedRulesCountConstant
.- Returns:
- an
IlrParameterMap
that contains all the "out" ruleset variables with their values. - See Also:
IlrParameterMap
-
isUsingFlow
public final boolean isUsingFlow()
Returns a boolean to indicate whether a ruleflow has been defined in the context's ruleset.
- Returns:
true
if a ruleflow is defined in the context's ruleset, else returnsfalse
.
-
endCurrentTask
public void endCurrentTask()
Ends the context's current task by executing its potential final actions and declaring it as Completed. This task has been suspended during the flow execution because its completion flag returned false.
-
execute
public IlrParameterMap execute(java.lang.String name)
Executes the task passed as the argument. This call is equivalent to call
setMainTask
with the passed task and thenexecute
.- Parameters:
name
- The task's name.- Returns:
- an IlrParameterMap containing the values of the "out", "inout" ruleset variables and the number of fired rules.
- See Also:
IlrParameterMap
-
executeTask
public IlrParameterMap executeTask()
Provides a step-by-step execution of the ruleflow. If the context's ruleset does not contain a ruleflow, it calls
fireRule
. Otherwise it executes one task and exits. The ruleflow retains the current task, and the next call toexecute
orexecuteTask
starts from the current task.- Returns:
- an
IlrParameterMap
containing the "out" and "inout" ruleset variable values and the number of rules fired. - See Also:
IlrParameterMap
-
setRuleflowExceptionHandler
public void setRuleflowExceptionHandler(IlrExceptionHandler handler)
Sets the exception handler responsible for catching runtime exceptions thrown during the execution of a ruleflow. Note that setting an exception handler is not mandatory. The handler will not only be called, when the exception occurs within ruleflow statement execution. For exception that occurs during rule execution of the ruleflow you must use @link
setExceptionHandler(IlrExceptionHandler)
- Parameters:
handler
- The exception handler in charge of catching ruleflow execution exceptions.
-
getTask
public IlrTask getTask(java.lang.String name)
Returns the task defined in the ruleflow and whose name is the one passed as the parameter. It returns
null
if no such task exists.- Parameters:
name
- The name of a task to return.- Returns:
- The task whose name is
name
.
-
getCurrentTask
public IlrTask getCurrentTask()
Returns the task that is currently executing or the task that is in a suspended state in the ruleflow. If the ruleset linked to the context contains no ruleflow, the returned value is
null
. If there is a ruleflow that is neither executing nor suspended, the returned value isnull
. When the ruleflow is suspended because of a suspended task (a task is suspended because its completion flag returned a value of false) the current task is this task. If this suspended task has been completed by theendCurrentTask
method, it is no longer the current task. The ruleflow's current task is the one that is suspended, that is, the task that models the ruleflow itself. If the ruleflow is suspended because of a task by task execution, the current task is the one that models the ruleflow itself.- Returns:
- The task currently executing in the ruleflow or the task in a suspended state.
-
resetRuleflow
public void resetRuleflow()
Resets ruleflow execution in the context. This is particularly relevant for a suspended ruleflow. The execution of this method will start ruleflow execution with the ruleflow's main task, and not with the ruleflow's current task.
-
isCacheRuleflowData
public final boolean isCacheRuleflowData()
Tests whether or not the ruleflow data is cached when
resetRuleflow()
is called.- Since:
- JRules 6.7
- Returns:
- The result of the test.
- See Also:
setCacheRuleflowData(boolean)
,resetRuleflow()
-
setCacheRuleflowData
public final void setCacheRuleflowData(boolean cache)
Sets whether or not to keep the cached ruleflow data when
resetRuleflow()
is called.When the ruleflow data is cached, some internal ruleflow execution objects are reused from one call to
execute()
to another. Otherwise, all the ruleflow internal objects are re-created at each call toexecute()
. You should try keeping the ruleflow data cached when the ruleflow has few application objects to process at one time during each individual call toexecute()
. Note that the internal ruleflow objects related to purely dynamic tasks cannot be reused even if the ruleflow data is cached, because they depend on runtime values and have to be recomputed when required.By default, the ruleflow data is not cached.
- Since:
- JRules 6.7
- Parameters:
cache
- The control flag.- See Also:
isCacheRuleflowData()
,resetRuleflow()
,execute()
-
isTaskCompleted
public boolean isTaskCompleted(java.lang.String name)
Tests whether the specified task is completed. A task is said to be Completed if it has ended (or not started) its execution. This state is different from a Suspended state, which means that the task execution did not finish: the final actions of the task have not been executed, and if we execute the flow again we start at the suspended task. If the task is not defined in the ruleset, this method throws an
IlrUndefinedTaskException
exception encapsulated into anIlrUserRuntimeException
exception.- Parameters:
name
- The task's fully qualified name.- Returns:
true
if the specified task is not executing, else returnsfalse
.
-
isRuleflowCompleted
public boolean isRuleflowCompleted()
Tests whether the ruleflow execution is completed, which means that the ruleflow execution is not interrupted because of either a suspended task or a task by task execution.
- Returns:
true
if the ruleflow execution is completed, else returnsfalse
.
-
-