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 names, ruleset names, and ruleset parameter names.

Use only a-z, A–Z, 0–9, and underscore (_) characters. For the first character, 0 through 9 are not 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 IlrStatefulSession supports several execute methods.
Restriction: For EJB3 rule sessions, passivation and activation are not supported.

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 Java EE application server. The implementation is embedded as a Java SE execution unit (XU). The Java EE implementations use full-fledged Java EE execution units.
Plain Old Java Objects (POJO): For Java EE environments with a simple Java object model. POJO models are available in Java EE application servers.
Enterprise JavaBeans (EJB): For Java EE environments that use Enterprise JavaBeans (EJBs). Access can be local or remote.
Message-driven rule beans (MDB): For asynchronous execution in Java EE containers that use message-driven rule beans or Java Message Services (JMS).

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 getExecutionId method in the client application to return decision identifiers (ID). You can override such identifiers by a call to the method IlrSessionRequest.setExecutionId.

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.