A rule session is a runtime connection between a client
and a rule engine. Rule sessions use up rule engine resources.
Rule sessions use class factories with which client applications
can reference an implementation of a session. Rule sessions involve
a request and a response and run on the canonical ruleset path. Rule
sessions are associated with one or more rulesets but the connection
to the rule engine is limited to one ruleset. Rule sessions can be
stateful or stateless.
Rule sessions have the following role:
- They provide a mechanism to access the list of all the rulesets
that are accessible by the underlying execution unit (XU).
- They define the type of session that a client establishes: stateful
or stateless.
- They provide a class loader to enable the XU to execute a ruleset
on any Java™ or XML XOM.
Rule sessions rely on the following concepts:
- Canonical ruleset paths
- Execution request and execution response
- Stateless and stateful sessions
- Factories
The API of rule sessions is presented in the ilog.rules.res.session package.
Based
on the type of the parameter declared in the ruleset signature, the
rule session automatically converts a String to an IlrSessionRequest when it uses IlrSessionResponse. Conversely,
an output parameter is returned as a String. For
more information, see Reading XML documents.
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: - 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 do not support case
sensitivity.
Examples of valid ruleset paths:
- /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
Execution request and execution response
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.
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.
- Stateful rule sessions
- Stateful rule sessions are linked to a single ruleset path and
authorize access to the working memory. Class IlrStatefulSession supports several execute methods.
Note: If
you use stateful rule sessions in transactional mode, all the objects
added to the working memory must implement the java.io.Serializable interface.
Factories
Rule
sessions are created by factories. 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 different 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 simple Java models are
available in Java EE application
servers.
- Enterprise JavaBeans (EJB)
- For Java EE environments
that use Enterprise Java Beans.
Access is possible both locally or remotely.
- 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.
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.