Author :  Hann Wei Toh <hannwei@computer.org>
Date   :  July 9, 2001


SimRulen (pronounced "sim-rule-an", stands for Simple Rule Engine)

[ This release makes the system more conformant to general ECA rule systems
  (Event-Condition-Action rule systems).  Rules now consist of two
  components, the condition and the action.  C++ functions can now be
  used in condition expressions through "modules".  Besides, action
  expressions may also have similar functions through the use of
  "action modules".  Please refer to the sample client source file and
  the files with names like "xxxStockxxx.xx" for usage information.
  The separation of the stock example from the rule system code has not 
  been done in this release, but it is hoped that it can be done soon. 
  (July 9, 2001) ]

Introduction :

This simple rule engine is written to enable rules to be specified
in a more flexible manner.  The format of rules accepted by the engine
is similar to that of one of the winning entries in ACM Java Quest 2000
which demonstrates an applet that accepts stock alert rules.

The rule engine enables the creation and evaluation of rules.  Each
rule is formed by an expression, which may consist of both arithmetic
and logical sub-expressions.  Upon the creation of a rule, the
corresponding expression is parsed and a binary tree is constructed
to represent each element of the expression.  Specifically, each
operator, number and variable in the expression is converted to
a node.  A group of nodes form the binary tree.

The engine has three IDL interfaces.  They correspond to the rule server,
the stock server and the notification server respectively.  The
implementations of the rule server and the stock server are provided.
The notification server is expected to be implemented by the user
of the engine.  The rule server accepts rule creation and activation
requests.  The stock server is meant for receiving stock updates.
Upon getting a stock update, the rules which have registered interests
with the stock concerned are evaluated.  If an evaluation yields a
positive result, a notification message is delivered to the
notification server.

At present, events which trigger the evaluation of rules are generated
upon the arrival of stock updates.  Changes may be made to the
rule engine implementation to enable event generations upon the arrival
of other information.  This means that the rules do not necessarily
have to be related to stock alerts.  They can be related to other
stuff, provided the rule engine implementation is modified accordingly.
Besides, the implementation of the notification server may also
deliver information back to the rule engine to trigger the generation
of other events, instead of merely converting the notification messages
into emails etc.

If the notification server is used to produce information that triggers 
the generation of other events, it should be noted that, though the
receipt of such information is serialized with the help of the
single-threaded ORB MICO and its ORBIIOPBlocking option, the combination
of a pair of event and action (the event refers to the item that
results in the sending of a notification message to the notification
server, while the action refers to the information subsequently
produced by the notification server and which then triggers the
generation of other events) is not serialized with respect to other
combinations of event-action pairs.  That is, if there are two
combinations of event-action pairs, E1-A1 and E2-A2, if E1 happens
before E2 (E1->E2), we cannot conclude that A1 will happen before A2
(A1->A2).  In short, there is no total order among event-action pairs.

An expression, which forms a rule, may contain these operators:
+ - * / == != > >= < <= && ||

An example is:
((3000 * NYSE0321.cp) + (5000 * NYSE1128.cp)) >= (2000 * NYSE4232.cp)

The expression above means:
if the sum of (the current price of the stock NYSE0321 multiplied by 3000)
and (the current price of the stock NYSE1128 multiplied by 5000) is larger
than or equal to (the current price of the stock NYSE4232 multiplied by 2000),
then send out the message that accompanies the expression (please refer to
the IDL interfaces) using the specified means (email, sms etc as specified
in a field accompanying the expression (please refer to the IDL interfaces).

The current implementation accepts stock-related rules.  It should not be
too hard to modify the implementation for other purposes.

For information on changes made in each version of the rule engine,
please refer to the file named CHANGES.

The support for groups of facts has been added in version 0.3.
This is done through the use of the concept of "shadows".  A group of
facts that can be referenced by a rule expression, if the group has
a defined shadow class.  The rule that wishes to register its
interest with the group, instead of a specific fact, can include the
name of the shadow, rather than the name of a specific fact, in the
rule expression.  Whenever a fact within the group encounters a state
change, the fact maps its state to the shadow, and then the shadow
informs the rule engine which rules have registered interests with it.
The rule engine will then evaluate the rules concerned.  A fact can be
included in more than one group.  The method 
RuleSystemKernel::updateStockInfo() demonstrates an example of registering
stocks with a stock group using the value of the stock group identifier
that comes in stock information update events.  Note that this implementation
supports the inclusion of a maximum of one group name per rule expression.
If two or more group names are included in a single rule expression, the
result is undefined.  In any case, the groups that are not having 
state changes currently will always have the values mapped from the 
previous state changes.


License :

The code is released under GPL.  The license terms that apply to MICO also
apply to SimRulen.

