6 Rules Applications That Span Multiple Tiers

6.1 Creating Rules Applications That Span Multiple Tiers

To handle rules applications with certain rules having their action execution occurring on the application server, you must configure the rule class for external execution (in addition to configuring the action callback procedure). The steps to do this are similar to those described in Section 2.3, but are modified as follows:

1. Create the event structure as an object type in the database (same as Step 1 in Section 2.3).

2. Create the TravelPromotion rule class. Also define the results view, even though you may not use it initially. The results view can be used, for example, to create the TravelPromotion rule class, such that for each rule session (that processes some events for a rule class), the action execution can switch at runtime between either the action callback procedure (calling dbms_rlmgr.process_rules( ) as shown in Step 5 in Section 2.3) or external action execution (calling dbms_rlmgr.add_event( ), as shown in Step 5 in this section). For this purpose, the rule class is configured with an action callback procedure and a results view, as shown in the following example:

   BEGIN
      dbms_rlmgr.create_rule_class (
                  rule_class   => 'TravelPromotion',
                  event_struct => 'AddFlight',
                  action_cbk   => 'PromoAction',
                  rslt_viewnm  => 'MatchingPromos',
                  actprf_spec  => 'PromoType VARCHAR2(20),
                                   OfferedBy VARCHAR2(20)');
   END;
   

   Note that this command creates the following MatchingPromos results view to hold the results from the rule evaluation. This view uses a fixed set of columns to list the system generated event identifier (rlm$eventid), the event instance (rlm$event for a (simple) primitive event), the rule identifier for the matching rules (rlm$ruleid), the rule condition (rlm$rulecond), the rule description (rlm$ruledesc), and a variable set of columns to represent the action preferences associated with the rules (PromoType and OfferedBy columns in this example). For an event matching a set of rules in the rule class, the information about the event and the matched rules can be obtained by querying this view.

   VIEW MatchingPromos (
                    rlm$eventid    ROWID,
                    rlm$event      AddFlight,
                    rlm$ruleid     VARCHAR2(100),
                    PromoType      VARCHAR2(20),
                    OfferedBy      VARCHAR2(20)),
                    rlm$rulecond   VARCHAR2(4000),
                    rlm$ruledesc   VARCHAR2(1000,
                    rlm$enabled    CHAR(1) DEFAULT 'Y');
   );
   

   The results view in the case of a rule class configured for a composite event is structured to hold the results from evaluating the rules using one or more primitive events. For this purpose, this view is created with separate columns for each primitive event within the composite event. For example, the following results view is created for the rule class defined in Section 2.4.1:

   VIEW  CompMatchingPromos (
                 rlm$eventid    ROWID,
                 Flt            AddFlight,
                 Car            AddRentalCar,
                 rlm$ruleid     VARCHAR2(100),
                 PromoType      VARCHAR2(20),
                 OfferedBy      VARCHAR2(20),
                 rlm$rulecond   VARCHAR2(4000),
                 rlm$ruledesc          VARCHAR2(1000)
                 rlm$enabled    CHAR(1) DEFAULT 'Y');
   

3. Implement the action callback procedure (same as Step 3 in Section 2.3).

4. Add rules to the rule class (same as Step 4 in Section 2.3).

5. Identify the matching rules for an event. This step replaces the use of the process rules procedure (dbms_rlmgr.process_rules( )) that identifies the matching rules and executes the corresponding actions with an add event procedure (dbms_rlmgr.add_event( )) that adds the event to the rule class one at a time and identifies the matching rules for a given event that are later accessed using the MatchingPromos results view.

   BEGIN
   dbms_rlmgr.add_event (
      rule_class  => 'TravelPromotion',
      event_inst  => AddFlight.getVarchar(987, 'Abcair', 'Boston', 'Orlando', '01-APR-2003', '08-APR-2003'));
   END;
   

6. Find the matching rules by querying the results view. For example, the following query returns a list of all the events added in the current session and their corresponding matching rules (and their action preferences):

   SELECT rlm$eventid, rlm$ruleid, PromoType, OfferedBy FROM MatchingPromos;
   

   Use the results from this query to execute the appropriate action in the application server. In the case of a rule class defined for a single event structure, this view implicitly has a rlm$eventid column that returns a system generated event identifier and rlm$event column to return the actual event as the (primitive event structure's) object instance.

   When you need to identify one candidate rule from the result set (conflict resolution), you can use ORDER BY, GROUP BY, and HAVING clauses. Note that the callback mechanism for action execution can only use ORDER BY semantics for conflict resolution. See Section 3.2 for more information. For example, if the Travel Services application offers only one promotion of each type, the following analytical query can be used to identify the appropriate rules to be fired:

   SELECT rlm$eventid, rlm$ruleid, PromoType, OfferedBy 
   FROM (SELECT rlm$eventid, rlm$ruleid, PromoType, OfferedBy,
                ROW_NUMBER( ) over (PARTITION BY PromoType
                                    ORDER BY rlm$ruleid) rnum
         FROM MatchingPromos)
   WHERE rnum=1;
   

   In this example, the rule identified as the one to be fired is the first one (rnum=1) returned from the query of the result set for the set of rules that evaluated to be true, partitioned by the type of promotion and ordered in ascending order by the rlm$ruleid column value.

   The results from a rule evaluation are available until the end of the rule session. By default, the database session (from connect to disconnect) is considered the rule session. Alternatively, you can use the reset session procedure (dbms_rlmgr.reset_session( )) to end a rule session and start a new session within a database session. Note that at the beginning of a rule session, the results view is empty.

7. Consume the event that is used in a rule execution. You can mark an event for exclusive or shared execution of rules by specifying the consumption policy for the events. Previously, in Section 2.3, if the TravelPromotion rule class was configured for exclusive consumption of events, then an event used for the execution of a rule was immediately deleted from the system and it could not be used for any other (matching) rules. Because the action callback procedure is used, Rules Manager automatically handles the consumption of the exclusive events. However, when you use external action execution, the application should explicitly consume the event chosen for an action execution by using the consume event procedure (dbms_rlmgr.consume_event( )). This procedure ensures that when multiple concurrent sessions try to consume the same event, only one of them succeeds. So, you should execute the action for a particular rule if the event is successfully consumed, as follows:

   DECLARE 
     consumed  number;
   BEGIN 
     consumed := dbms_rlmgr.consume_event (
                         rule_class => 'TravelPromotion',
                         event_ident => :eventIdBind);
     IF (consumed = 1) THEN 
       OfferPromotion(…);  -- offer the promotion only if the event 
                           -- consumption is successful
     END IF;
   END;
   

   Obtain the event identifier from the value listed in the rlm$eventid column of the MatchingPromos results view. If the consumption policy (see Section 3.2) for all events is shared, then the CONSUME_EVENT call always returns 1 and the event is still available. Note that only the events you configure for exclusive consumption are consumed and the corresponding rows from the results view are deleted.

6.2 Modes of Operation

Designing a rule-based application using Rules Manager involves a varying number of steps, depending on its mode of operation. Almost all the steps in both cases, single tier and multitier, are one-time implementations. Once these implementations are in place, you no longer need to deal with the Rules Manager APIs. You add new rules using the SQL INSERT statement against the rule class table and the run-time calls that are embedded in larger applications automatically process these new rules.

A rule class stored in the database can operate in either of the following two modes:

• Single tier mode -- the rule evaluation, identification of the candidate rules or action for execution, execution of action, and optional consumption of events all happen in the database with a single PROCESS_RULES call (which passes in the event instance). Note that this is the most common case even for applications running outside the database.

• Multitier mode -- the rule evaluation happens in the database and the remaining steps described in single-tier mode can be done in any tier with appropriate database calls (with a maximum of four steps, which are described in Section 6.2.2).