Rule sessions

A rule session is a runtime connection between a client and a rule engine. Rule sessions use rule engine resources.

Rule sessions are associated with one or more rulesets but the connection to the rule engine is limited to one ruleset.

The rule session API provides the following services:
  • Access to the list of all the rulesets and RuleApps that are deployed in Rule Execution Server repository.
  • Execution of rulesets.
Rule sessions rely on the following concepts:

The API of rule sessions is presented in the ilog.rules.res.session package.

Execution request and execution response

Rule sessions involve a request (IlrSessionRequest) and a response (IlrSessionResponse). You use session requests to execute rulesets through stateless rule sessions. Session requests contain information for the execution of the ruleset, such as IN parameters and trace settings. Session responses contain information that is returned from stateless ruleset execution such as OUT/INOUT parameters and trace data.

Ruleset path

Rule sessions run on the ruleset path. Rule Execution Server uses the path of a deployed ruleset to locate the ruleset and the RuleApp to which it belongs. Ruleset paths are instances of the class IlrPath.

The ruleset path is referred to as canonical when it specifies the RuleApp name and version number, and the ruleset name and version number, as follows:

/{RuleApp name}[/{version}]/{ruleset name}[/{version}]
  • The {RuleApp name} and {ruleset name} elements are both mandatory.
  • The /{version} element is optional. If the version is not specified, the latest activated version of the RuleApp or ruleset is used. {version} is equivalent to {number}.{number}.
Restriction:
Not all characters are allowed in RuleApp and ruleset names:
  • Use only letters, digits and underscore (_) characters.
  • The first character cannot be a digit (0-9).
  • Unicode characters identified as letters are allowed.
If you set Rule Execution Server persistence to file, remember that Windows environments are not case sensitive.
Table 1. Valid ruleset paths
Valid ruleset path
/rule8_8app/6_ruleset_6/1.0
/rule8_8app/1.0/6_ruleset_6
/rule8_8app/6_ruleset_6
/rule8_8app/1.0/6_ruleset_6/1.0

To specify ruleset paths, you can also use ruleset interceptors.

Stateless and stateful rule sessions

Rule sessions can be stateful or stateless.
Stateless rule sessions
Stateless rule sessions are execution sessions that handle no state: between two method calls, the session does not maintain any data or engine information. Stateless rule sessions are instances of the class IlrStatelessSession. In stateless rule sessions, you can execute rulesets asynchronously by inserting an observer between the execution request and the execution start, depending on execution events. To insert an observer, implement the IlrAsyncExecutionObserver interface.
Stateful rule sessions
Stateful rule sessions are linked to a single ruleset path and enable access to the working memory. Class IlrStatefulSessio supports several execute methods.

Factories

To create rule sessions, you use class factories with which client applications can reference an implementation of a session. Factories are entry points for calling Rule Execution Server through the rule session API. You can use the methods of the IlrSessionFactory interface to create stateful, stateless, and management sessions, to create execution requests, and to enable interceptors.

Implementations are provided for various application environments:
Java™ SE
For Java SE environments or web-only containers. With Java SE factories, you can use rule sessions outside of a Jakarta EE application server. The implementation is embedded as a Jakarta SE execution unit (XU). The Jakarta EE implementations use full-fledged Jakarta EE execution units.
Plain Old Java Objects (POJO)
For Jakarta EE environments with a simple Java object model. POJO models are available in Jakarta EE application servers.

Typically, you instantiate a rule session factory for the target environment and then you use the resulting object to access rule sessions. See the ilog.rules.res.session package description for a code sample.

Ruleset parameters

The input parameters that are declared in the ruleset signature as XML or BOM types must be passed as java.lang.String objects. The output parameters that are declared in the ruleset signature as XML or BOM types are returned as java.lang.String objects.

Decision identifiers

You can use the rule session API and the IlrSessionResponse#getExecutionId() method in the client application to return decision identifiers (ID). You can override such identifiers by a call to the method IlrSessionRequest.IlrSessionRequest#setExecutionId(java.lang.String).

You can use decision IDs in Decision Warehouse to locate a specific transaction and view the executed rules.
Attention: When you define a decision ID, make sure that it is unique. Otherwise, the client receives a response but that response is not registered in Decision Warehouse. A warning is issued in the output string.