IlrStatefulSession (Rule Execution Server API)

All Superinterfaces:

IlrSession

All Known Subinterfaces:

IlrStatefulSessionEJB
```
public interface IlrStatefulSession
extends IlrSession
```
IlrStatefulSession represents a stateful rule session.
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 stateful rule session can pass objects as input parameters with the method execute(Map). It can also add them to the working memory insertJavaObjects(List).
The reset of an IlrStatefulSession instance calls the reset of the engine.

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

Methods
Modifier and Type	Method and Description
`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(java.util.Map<java.lang.String,java.lang.Object> inputParameters)` Executes a ruleset by using the input parameters.
`IlrSessionResponse`	`execute(java.util.Map<java.lang.String,java.lang.Object> inputParameters, java.lang.String taskName)` Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow.
`IlrSessionResponse`	`execute(java.util.Map<java.lang.String,java.lang.Object> inputParameters, java.lang.String taskName, boolean isBOMAccess)` Executes a ruleset by using the input parameters and starting from a specific task in the ruleflow.
`java.lang.String`	`getOutput()` Returns the engine output as a String.
`java.util.Map<java.lang.String,java.lang.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.
`java.util.Collection<IlrRulesetParameter>`	`getRulesetSignature()` Retrieves the ruleset parameters.
`IlrTraceFilter`	`getTraceFilter()` Returns the trace filter that is used to collect trace data.
`java.io.Serializable`	`getUserData()` Returns the user data supplied at construction time, that is, when this stateful session was created.
`java.util.List<IlrWarning>`	`getWarnings(boolean clear)` Returns the warnings that are generated by the execution unit (XU).
`java.util.List<java.lang.Object>`	`getWorkingMemory()` Returns all the objects in the working memory.
`java.util.Map<java.util.UUID,java.lang.Object>`	`getWorkingMemoryUUIDs()` Returns all the objects with UUIDs in the working memory.
`java.util.List<java.util.UUID>`	`insertJavaObjects(java.util.List<java.lang.Object> objects)` Inserts objects into the working memory.
`java.util.List<java.util.UUID>`	`insertXMLObjects(java.util.List<java.lang.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(java.util.List<java.util.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(java.util.List<java.util.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
```
java.io.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
```
java.lang.String getOutput()
                           throws IlrSessionException
```
    Returns the engine output as a String. When you use CRE, ilog.rules.engine.IlrContext.note writes into this output.
    
    Throws:
    
    An - IlrSessionException object if an error occurs when the output string is returned.
    
    IlrSessionException
    
    Returns:
    The engine output as a String.
  - 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(java.util.Map<java.lang.String,java.lang.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(java.util.Map<java.lang.String,java.lang.Object> inputParameters,
                         java.lang.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(java.util.Map<java.lang.String,java.lang.Object> inputParameters,
                         java.lang.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
```
java.util.List<java.util.UUID> insertJavaObjects(java.util.List<java.lang.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
```
java.util.List<java.util.UUID> insertXMLObjects(java.util.List<java.lang.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(java.util.List<java.util.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(java.util.List<java.util.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
```
java.util.List<java.lang.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
```
java.util.Map<java.util.UUID,java.lang.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
```
java.util.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
```
java.util.Collection<IlrRulesetParameter> getRulesetSignature()
                                                              throws IlrSessionException
```
    Retrieves the ruleset parameters.
    
    Since:
    
    7.5
    
    Throws:
    
    IlrSessionException
  - getRulesetArchiveProperties
```
java.util.Map<java.lang.String,java.lang.String> getRulesetArchiveProperties()
                                                                             throws IlrSessionException
```
    Retrieves the properties of the ruleset archive.
    
    Since:
    
    7.5
    
    Throws:
    
    IlrSessionException

getRulesetPath

getUserData

isInterceptorEnabled

isRulesetUptodate

isTraceEnabled

setTraceEnabled

getTraceFilter

setTraceFilter

getOutput

execute

execute

execute

execute

insertJavaObjects

insertXMLObjects

update

retract

getWorkingMemory

getWorkingMemoryUUIDs

reset

resetRuleflow

getWarnings

close

getRulesetSignature

getRulesetArchiveProperties