Skip navigation links

ilog.rules.res.session
Interface IlrStatefulSession

All Superinterfaces:

IlrSession

All Known Subinterfaces:

IlrStatefulSessionEJB

public interface IlrStatefulSession
extends IlrSession

IlrStatefulSession represents a stateful rule session.

Overview

A stateful session is a rule session where the server stores the engine state and provides access to the working memory.

Use stateful rule sessions for the following actions:

• Set input (in) parameters
• Get output (out) parameters
• Access the working memory

You must work with stateful sessions when you want to change the state of a Java SE, POJO, or EJB component - that is, to insert and update objects in the working memory or retract objects from it.

A stateless rule session can pass objects as input parameters, then add them to the working memory by using a rule task initial action. You can do the same with output parameters. The working memory content can be modified at the end of an execution.

To reset an IlrStatefulSession instance, you must reinitialize the engine.

Code example

The following code example shows how to execute rules in a stateful session.

   IlrPath rulesetPath = IlrPath.parsePath("/simplejava/simplejavaruleset");
   IlrStatefulSession session = null;
   try {
     session = sessionFactory.createStatefulSession(rulesetPath, null, null, false);
     session.setTraceEnabled(true);
     session.getTraceFilter().setInfoWorkingMemory(false);
     session.getTraceFilter().setInfoRules(true);
     Map params = new HashMap();
     params.put("param1", "Value1");
     IlrSessionResponse response = session.execute(params);
     IlrExecutionTrace trace = response.getRulesetExecutionTrace();
   } finally {
     if (session!=null) {
       session.close();
     }
   }
 

Since:

7.0

Method Summary

void	close() Closes this session.
IlrSessionResponse	execute() Executes a ruleset, based on the current state of the engine and the state of the session.
IlrSessionResponse	execute(Map<String,Object> inputParameters) Executes a ruleset by using the input parameters.
IlrSessionResponse	execute(Map<String,Object> inputParameters, String taskName) Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow.
IlrSessionResponse	execute(Map<String,Object> inputParameters, String taskName, boolean isBOMAccess) Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow.
String	getOutput() Returns the value of the IlrContext.out stream.
Map<String,String>	getRulesetArchiveProperties() Retrieves the properties of the ruleset archive.
IlrPath	getRulesetPath() Returns the ruleset path that was specified at construction time, that is, when this stateful session was created.
Collection<IlrRulesetParameter>	getRulesetSignature() Retrieves the ruleset parameters.
IlrTraceFilter	getTraceFilter() Returns the trace filter that is used to collect trace data.
Serializable	getUserData() Returns the user data supplied at construction time, that is, when this stateful session was created.
List<IlrWarning>	getWarnings(boolean clear) Returns the warnings that are generated by the execution unit (XU).
List<Object>	getWorkingMemory() Returns all the objects in the working memory.
Map<UUID,Object>	getWorkingMemoryUUIDs() Returns all the objects with UUIDs in the working memory.
List<UUID>	insertJavaObjects(List<Object> objects) Inserts objects into the working memory.
List<UUID>	insertXMLObjects(List<String> objects) Inserts XML objects into the working memory.
boolean	isInterceptorEnabled() Tests whether the interceptors are enabled.
boolean	isRulesetUptodate() Tests whether the underlying ruleset used by this session is up to date with respect to the Rule Execution Server repository.
boolean	isTraceEnabled() Tests whether the trace is enabled.
void	reset() Clears data from this object.
void	resetRuleflow() Resets the ruleflow.
void	retract(List<UUID> uuids) Removes specific objects from the working memory.
void	setTraceEnabled(boolean enabled) Enables or disables the trace.
void	setTraceFilter(IlrTraceFilter filter) Sets the trace filter that is used to collect trace data.
void	update(List<UUID> uuids) Sends a notification when a set of objects in the working memory has been changed.

Method Detail

getRulesetPath

IlrPath getRulesetPath()

Returns the ruleset path that was specified at construction time, that is, when this stateful session was created.

Returns:

The ruleset path to be used for execution.

getUserData

Serializable getUserData()

Returns the user data supplied at construction time, that is, when this stateful session was created.

Returns:

The user data supplied at construction time.

isInterceptorEnabled

boolean isInterceptorEnabled()

Tests whether the interceptors are enabled.

Returns:

true if the interceptors are enabled.

isRulesetUptodate

boolean isRulesetUptodate()
                          throws IlrSessionException

Tests whether the underlying ruleset used by this session is up to date with respect to the Rule Execution Server repository.

As soon as the execution unit (XU) is notified of a change on the ruleset of the session, this method returns false. This result enables the caller to open a new session to use the up-to-date ruleset.

Since:

8.5.1

Throws:

IlrSessionException - An IlrSessionException object if an error occurred while the session was checking whether the ruleset is up to date.

Returns:

true if the ruleset is up to date.

isTraceEnabled

boolean isTraceEnabled()

Tests whether the trace is enabled.

Returns:

true if the trace is enabled.

setTraceEnabled

void setTraceEnabled(boolean enabled)

Enables or disables the trace. By default, the trace is disabled.

Parameters:

enabled - Set to true to enable the trace.

getTraceFilter

IlrTraceFilter getTraceFilter()

Returns the trace filter that is used to collect trace data. This filter is used only when the trace is enabled.

Returns:

The trace filter.

setTraceFilter

void setTraceFilter(IlrTraceFilter filter)

Sets the trace filter that is used to collect trace data. This filter is used only when the trace is enabled.

Parameters:

filter - The new trace filter.

getOutput

String getOutput()
                 throws IlrSessionException

Returns the value of the IlrContext.out stream.

Throws:

An - IlrSessionException object if an error occurs when the output string is returned.

IlrSessionException

Returns:

The value of the IlrContext.out stream.

execute

IlrSessionResponse execute()
                           throws IlrSessionException

Executes a ruleset, based on the current state of the engine and the state of the session.

Throws:

An - IlrSessionException object if an error occurred during ruleset execution.

IlrSessionException

Returns:

The execution response.

execute

IlrSessionResponse execute(Map<String,Object> inputParameters)
                           throws IlrSessionException

Executes a ruleset by using the input parameters. This method takes into account the state of the engine and the session during execution.

Throws:

An - IlrSessionException object if an error occurred during ruleset execution.

IlrSessionException

Parameters:

inputParameters - A map that contains the input parameters.

Returns:

The execution response.

execute

IlrSessionResponse execute(Map<String,Object> inputParameters,
                           String taskName)
                           throws IlrSessionException

Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow. This method takes into account the state of the engine and the session during execution.

Throws:

An - IlrSessionException object if an error occurred during ruleset execution.

IlrSessionException

Parameters:

inputParameters - A map that contains the input parameters.

taskName - The name of the task to execute in the ruleflow.

Returns:

The execution response.

execute

IlrSessionResponse execute(Map<String,Object> inputParameters,
                           String taskName,
                           boolean isBOMAccess)
                           throws IlrSessionException

Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow. This method takes into account the state of the engine and the session during execution.

Throws:

An - IlrSessionException object if an error occurred during ruleset execution.

IlrSessionException

Parameters:

inputParameters - A map that contains the input parameters.

taskName - The name of the task to execute in the ruleflow.

isBOMAccess - Set to true so that the BOM-serialized version of the parameters is available in the execution response.

Returns:

The execution response.

insertJavaObjects

List<UUID> insertJavaObjects(List<Object> objects)
                             throws IlrSessionException

Inserts objects into the working memory.

Throws:

An - IlrSessionException object if an error occurs when these objects are added.

IlrSessionException

Parameters:

objects - A list of Object instances to be added to the working memory.

Returns:

A list that contains the UUID of the objects to be added.

insertXMLObjects

List<UUID> insertXMLObjects(List<String> objects)
                            throws IlrSessionException

Inserts XML objects into the working memory.

Throws:

An - IlrSessionException object if an error occurs when the XML objects are added.

IlrSessionException

Parameters:

objects - A list of String objects to be added to the working memory.

Returns:

A list that contains the UUID of the XML objects to be added.

update

void update(List<UUID> uuids)
            throws IlrSessionException

Sends a notification when a set of objects in the working memory has been changed.

Throws:

An - IlrSessionException object if an error occurs when the object is updated.

IlrSessionException

Parameters:

uuids - The UUIDs of the objects to be notified.

retract

void retract(List<UUID> uuids)
             throws IlrSessionException

Removes specific objects from the working memory.

Throws:

IlrSessionException - if an error occurs when the objects are removed.

Parameters:

uuids - The UUIDs of the objects to be removed.

getWorkingMemory

List<Object> getWorkingMemory()
                              throws IlrSessionException

Returns all the objects in the working memory.

Throws:

An - IlrSessionException object if an error occurred when the working memory is returned.

IlrSessionException

Returns:

All the objects in the working memory.

getWorkingMemoryUUIDs

Map<UUID,Object> getWorkingMemoryUUIDs()
                                       throws IlrSessionException

Returns all the objects with UUIDs in the working memory.

Throws:

An - IlrSessionException object if an error occurs while the UUIDs are retrieved.

IlrSessionException

Returns:

All the objects with UUIDs in the working memory.

reset

void reset()
           throws IlrSessionException

Clears data from this object. This method removes the following elements:

• All objects from the working memory.
• All the rules from the agenda.
• All the parameter values that were previously set.
• All the traces from previous operations on the engine.

Throws:

An - IlrSessionException object if an error occurs.

IlrSessionException

resetRuleflow

void resetRuleflow()
                   throws IlrSessionException

Resets the ruleflow.

Throws:

IlrSessionException - if an error occurs when the ruleflow is reset.

getWarnings

List<IlrWarning> getWarnings(boolean clear)

Returns the warnings that are generated by the execution unit (XU).

Parameters:

clear - Set to true to check whether the warnings kept by the session must be cleared.

Returns:

A list of IlrSessionWarning objects. If no warnings are emitted, this list is empty.

close

void close()

Closes this session.

getRulesetSignature

Collection<IlrRulesetParameter> getRulesetSignature()
                                                    throws IlrSessionException

Retrieves the ruleset parameters.

Since:

7.5

Throws:

IlrSessionException

getRulesetArchiveProperties

Map<String,String> getRulesetArchiveProperties()
                                               throws IlrSessionException

Retrieves the properties of the ruleset archive.

Since:

7.5

Throws:

IlrSessionException