Ruleset interceptors

You can implement a ruleset interceptor on rule sessions to make ruleset selection depend on certain events that involve modified RuleApp or ruleset properties.

Ruleset interceptors intercept execution requests to fulfill the following roles:

Augment input parameters (compression, data)
Provide custom security checking
Route a request to a ruleset (using expiration dates for example)
Separate the logical ruleset path from the physical ruleset path

Use ruleset interceptors to select rulesets at run time based on some routing logic and to add services to execution components transparently. More specifically, you can use interceptors to complement the ruleset path, to modify the input parameters, and to execute. When you implement an interceptor on rule sessions, rulesets are automatically selected when certain events occur that involve the RuleApp or ruleset properties you have modified.

You can use interceptors both on stateless and on stateful rule sessions. The only difference lies in the way the methods are called.

You must have monitor rights to use interceptors. As a consequence, you must also have Java™ EE administration rights on the application server.

Use cases

A basic example consists in using properties to set start and end dates, and have Rule Execution Server call a ruleset automatically at a given date or time. Another typical use case is execution requests in which rules are different for various geographical areas.

More generally, you can use interceptors in the following cases:

To select a ruleset inside a RuleApp according to the value of XOM objects in the execution request.
To change the ruleset path inside a RuleApp according to the value of XOM objects in the execution request.
To add, remove, or modify ruleset parameter values in stateless rule sessions and message-driven rule beans.
In hosted transparent decision services. See Decision services.

API and packaging

By default, ruleset interceptors are not enabled on session requests. Therefore, to use a ruleset interceptor, your client application must first enable ruleset interceptors on its session request.

To do so, call the method setInterceptorEnabled(true) on the session request and session factory instances:

On IlrSessionRequest: After you have called this method on the session request, only this session request has ruleset interceptors enabled. Current and future session requests are not affected.
On IlrSessionFactory, before you create the session request. After you have called this method on the session factory, ruleset interceptors are enabled only future session requests that you create from this session factory.

You specify the interceptor through a Java class name. The Java class must implement the IlrSessionInterceptor interface.

To change the ruleset path used by the execution process, use the transformRsPath callback method by registering an interceptor. Stateless rule sessions call this method just before calling the beforeExecute method. Stateful sessions call the method only once when the session is created.

The interceptor is called first before execution, then after execution to carry out preprocessing and postprocessing actions. In the preprocessing phase, the interceptor modifies the executed ruleset by setting the input request and the RuleApp and ruleset properties.

You must package the class inside the client EAR, then register it with Rule Execution Server using the ruleapp.interceptor.classname RuleApp property. The class is loaded and instantiated inside the current client class loader and the method IlrSessionInterceptor.transformRsPath is called with an IlrSessionFactory object passed with a read-only tree of the RuleApp and ruleset properties. The transformRsPath method returns an IlrPath object which contains a canonical ruleset path to be called inside the specified RuleApp.

Run time

You can use interceptors both on stateless and on stateful rule sessions. However, the runtime process differs between stateless sessions and stateful sessions:

In stateless sessions:
1. The beforeExecute, transformRsPath, and afterExecute methods are called for each ruleset execution.
2. The transformRsPath and beforeExecute methods are executed before the ruleset is executed.
3. The afterExecute method is called just after the execution.
In stateful sessions:
1. The transformRsPath method is called only once, when the stateful session is created. This is because ruleset paths are immutable inside stateful sessions.
2. Then, the methods beforeExecute and afterExecute are called before and after each ruleset execution respectively, inside the same stateful session.