The DBMS_RLMGR package contains various procedures to create and manage rules and rule sessions by the Rules Manager.
See Also:
Oracle Database Application Developer's Guide - Rules Manager and Expression Filter for more information.This chapter contains the following topic:
Table 88-1 describes the subprograms in the DBMS_RLMGR package.
All the values and names passed to the procedures defined in the DBMS_RLMGR package are case insensitive unless otherwise mentioned. In order to preserve the case, double quotation marks should be used around the values.
Table 88-1 DBMS_RLMGR Package Subprograms
| Subprogram | Description |
|---|---|
|
Adds the specified attribute to the event structure (also the Expression Filter attribute set) |
|
|
Adds an event to a rule class in an active session |
|
|
Adds a Function, a Type, or a Package to the approved list of functions with an event structure (also the Expression Filter attribute set) |
|
|
Adds a rule to the rule class |
|
|
Consumes an event using its identifiers and prepares the corresponding rule for action execution |
|
|
Consumes one or more primitive events with all or none semantics |
|
|
Creates an event structure |
|
|
Creates a rule class |
|
|
Deletes a rule from a rule class |
|
|
Drops an event structure |
|
|
Drops a rule class |
|
|
Grants a privilege on a rule class to another user |
|
|
Process the rules for a given event |
|
|
Starts a new rule session within a database session |
|
|
Revokes a privilege on a rule class from a user |
This procedure adds the specified attribute to an event structure, which is also the Expression Filter attribute set. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.
Adds the specified elementary attribute to the attribute set:
DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
event_struct IN VARCHAR2,
attr_name IN VARCHAR2,
attr_type IN VARCHAR2,
attr_defvl IN VARCHAR2 default NULL);
Identifies the elementary attributes that are table aliases and adds them to the event structure:
DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
event_struct IN VARCHAR2,
attr_name IN VARCHAR2,
tab_alias IN rlm$table_alias);
Table 88-2 ADD_ELEMENTARY_ATTRIBUTE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
Name of the event structure or attribute set to which this attribute is added |
|
|
Name of the elementary attribute to be added. No two attributes in a set can have the same name. |
|
|
Datatype of the attribute. This argument accepts any standard SQL datatype or the name of an object type that is accessible to the current user. |
|
|
The type that identifies the database table to which the attribute is aliased |
|
|
Default value for the elementary attribute |
This procedure adds an elementary attribute to an event structure. The event structure is internally managed as the Expression Filter attribute set. If the event structure was originally created from an existing object type, then additional attributes cannot be added.
Elementary attributes cannot be added to an attribute set that is already assigned to a column storing expressions, which is equivalent to an event structure that is used for a rule class.
One or more, or all elementary attributes in an attribute set can be table aliases. If an elementary attribute is a table alias, then the value assigned to the elementary attribute is a ROWID from the corresponding table. An attribute set with one or more table alias attributes cannot be created from an existing object type. For more information about table aliases, see Appendix A in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter.
Elementary attributes cannot be added to an attribute set that is already assigned to a column storing expressions.
See "Defining Attribute Sets" in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter for more information about adding elementary attributes.
Related views: USER_EXPFIL_ATTRIBUTE_SETS and USER_EXPFIL_ATTRIBUTES.
The following commands add two elementary attributes to an attribute set:
BEGIN
DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
event_struct => 'HRAttrSet',
attr_name => 'HRREP',
attr_type => 'VARCHAR2(30)');
DBMS_RLMGR.ADD_ELEMENTARY_ATTRIBUTE (
event_struct => 'HRAttrSet',
attr_name => 'DEPT',
tab_alias => exf$table_alias('DEPT'));
END;
This procedure adds a primitive event to a rule class in an active rule session. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.
Adds a string representation of the primitive event instance to a rule class:
DBMS_RLMGR.ADD_EVENT ( rule_class IN VARCHAR2, event_inst IN VARCHAR2, event_type IN VARCHAR2 default null);
Adds an AnyData representation of the primitive event instance to a rule class:
DBMS_RLMGR.ADD_EVENT ( rule_class IN VARCHAR2, event_inst IN sys.AnyData);
Table 88-3 ADD_EVENT Procedure Parameters
| Parameter | Description |
|---|---|
|
|
Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
String or AnyData representation of the event instance being added to the rule class |
|
|
Type of event instance assigned to the |
This procedure is used to add a primitive or a simple event to a rule class within an active rule session. By default, a rule session is the same as the database session. Optionally, multiple (sequential) rule sessions can be started within a database session by using the RESET_SESSION or PROCESS_RULES procedures.
When the rule class is configured for simple events (consisting of only one primitive event structure), the event_type argument for the ADD_EVENT procedure can be ignored. Also, when the AnyData format of the event instance is passed, the event type information is embedded in the AnyData instance. In all other cases, the name of the primitive event structure being added to the rule class should be assigned to the event_type argument.
For a valid event instance, the ADD_EVENT procedure processes the rules in the rule class and captures the results in the rule class results view (configured at the time of rule class creation). These results are preserved until the end of the rule session.When schema extended name is used for the rule class, you should have PROCESS RULES privilege on the rule class. See the GRANT_PRIVILEGE Procedure for additional information. The value specified for the event_type argument is always resolved in the rule class owner's schema and should not use schema extended names. When a composite event structure is configured with a table alias primitive event type, the name of the corresponding table should be assigned to the event_type argument.
The following commands add two events to the CompTravelPromo rule class that is configured for two types of primitive events (AddFlight and AddRentalCar).
BEGIN
DBMS_RLMGR.ADD_EVENT(rule_class => 'CompTravelPromo',
event_inst =>
AddFlight.getVarchar(987, 'Abcair', 'Boston',
'Orlando', '01-APR-2003', '08-APR-2003'),
event_type => 'AddFlight');
DBMS_RLMGR.ADD_EVENT(rule_class => 'Scott.CompTravelPromo',
event_inst =>
AnyData.convertObject(
AddRentalCar(987, 'Luxury', '03-APR-2003',
'08-APR-2003', NULL)));
END;
This procedure adds a user-defined function, package, or type representing a set of functions to the event structure, which is also the Expression Filter attribute set.
DBMS_RLMGR.ADD_FUNCTIONS ( event_struct IN VARCHAR2, funcs_name IN VARCHAR2);
Table 88-4 ADD_FUNCTIONS Procedure Parameters
| Parameter | Description |
|---|---|
|
|
Name of the event structure to which the functions are added |
|
|
Name of a function, package, or type (representing a function set) or its synonyms |
By default, an attribute set implicitly allows references to all Oracle supplied SQL functions for use in the rule conditions. If the expression set refers to a user-defined function, the expression set must be explicitly added to the attribute set.
The ADD_FUNCTIONS procedure adds a user-defined function or a package (or type) representing a set of functions to the attribute set. Any new or modified expressions are validated using this list.
The function or the package name can be specified with a schema extension. If a function name is specified without a schema extension, only such references in the rule condition are considered valid. The conditional expression can be restricted to use a synonym to a function or a package by adding the corresponding synonym to the attribute set. This preserves the portability of the expression set to other schemas.
See "Defining Attribute Sets" in Oracle Database Application Developer's Guide - Rules Manager and Expression Filter for more information about adding functions to an attribute set.
Related views: USER_EXPFIL_ATTRIBUTE_SETS and USER_EXPFIL_ASET_FUNCTIONS
The following commands add two functions to the attribute set:
BEGIN
DBMS_RLMGR.ADD_FUNCTIONS (attr_set => 'Car4Sale',
funcs_name => 'HorsePower');
DBMS_RLMGR.ADD_FUNCTIONS (attr_set => 'Car4Sale',
funcs_name => 'Scott.CrashTestRating');
END;
This procedure adds new rules to a rule class.
DBMS_RLMGR.ADD_RULE ( rule_class IN VARCHAR2, rule_id IN VARCHAR2, rule_cond IN VARCHAR2, actprf_nml IN VARCHAR2 DEFAULT NULL, actprf_vall IN VARCHAR2 DEFAULT NULL);
Table 88-5 ADD_RULE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
Unique identifier for the rule within the rule class |
|
|
The condition for the rule. The condition uses the variables defined in the rule class's event structure. |
|
|
The list of action preference names for which values will be assigned through the |
|
|
The list of action preference values for the names list assigned to the |
This procedure is used to add new rules to the rule class. The rule condition passed to the ADD_RULE procedure is validated using the event structure associated with the rule class. The action preferences names list is a subset of action preference categories configured during rule class creation.
When schema extended name is used for the rule class, you should have ADD RULE privilege on the rule class. See the GRANT_PRIVILEGE Procedure for more information.
Alternately, the owner of the rule class can add the rules using SQL INSERT statement on the rule class table (that shares the same name as the rule class). Note that the owner of the rule class can also grant direct DML privileges on the rule class table to other users.
Note:
The AUTOCOMMIT property of the rule class is ignored if the new rules are added using the SQL INSERT statement instead of the ADD_RULE procedure.See the CREATE_RULE_CLASS Procedure procedure for the structure of the rule class table.
The following command adds a rule to the rule class.
BEGIN
DBMS_RLMGR.ADD_RULE (
rule_class => 'CompTravelPromo',
rule_id => 'AB_AV_FL',
rule_cond =>
'<condition>
<and join="Flt.CustId = Car.CustId">
<object name="Flt">
Airline=''Abcair'' and ToCity=''Orlando''
</object>
<object name="Car">
CarType = ''Luxury''
</object>
</and>
</condition>' ,
actprf_nml => 'PromoType, OfferedBy',
actprf_vall => '''RentalCar'', ''Acar''');
END;
With proper privileges, the following SQL INSERT statement can be used to add the rule to the rule class.
INSERT INTO CompTravelPromo (rlm$ruleid, rlm$rulecond, PromoType, OfferedBy)
VALUES ('AB_AV_FL',
'<condition>
<and join="Flt.CustId = Car.CustId">
<object name="Flt">
Airline=''Abcair'' and ToCity=''Orlando''
</object>
<object name="Car">
CarType = ''Luxury''
</object>
</and>
</condition>',
'RentalCar','Acar');
This function consumes an event and prepares the corresponding rule for action execution. This is required only when the action (or rule execution) is carried by the user's application and not in the callback.
DBMS_RLMGR.CONSUME_EVENT ( rule_class IN VARCHAR2, event_ident IN VARCHAR2) RETURN NUMBER;
Table 88-6 CONSUME_EVENT Function Parameters
| Parameter | Description |
|---|---|
|
|
Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
Event identifier obtained from the corresponding rule class results view (or arguments of the action callback procedure in the case of rule class configured for RULE based consumption policy) |
The function returns:
1 -- If the event is successfully consumed.
0 -- If the event is expired (owing to duration policy) or consumed by another session prior to this call.
When an EXCLUSIVE consumption policy is set for the events in a rule class, an event must be deleted from the system immediately after the rule it matched is executed (action is executed). When the rule action is carried in the rule class callback procedure by calling the PROCESS_RULES procedure, the rule manager automatically handles the consumption of the events. However, when you request the results from matching events with rules in a rule class results view using the ADD_EVENT procedure, you should take appropriate action to indicate the exact rule-event combination that is to be used for rule execution. The CONSUME_EVENT procedure performs the required housekeeping services when the unique identifier for the event used in a rule execution is passed in.
Since there could be a time lag between fetching the rule class matching results and the execution of the user initiated action, the application should execute the action only if the CONSUME_EVENT call succeeds in consuming the event. This avoids any race condition with parallel sessions trying to consume the same events. When the event is successfully consumed, this call returns 1. In all other cases, it returns 0. A return value of 0 implies that the event is already consumed by another session and hence it is not available for this session.
The CONSUME_EVENT procedure deletes the events configured with EXCLUSIVE consumption policy and does nothing for events configured for 4 consumption policy.
Unlike the EXCLUSIVE and SHARED consumption policies, which are determined at the rule class level, a RULE consumption policy can be used to determine the consumption of an event on a rule by rule basis. That is a subset of the rules in a rule class may be configured such that when they are matched, the event is deleted from the system. At the same time the other set of rules could leave the event in the system even after executing the corresponding action. In this scenario, the action callback procedure implemented by the application developer can call CONSUME_EVENT function (with appropriate arguments) to conditionally consume the event for certain rules. Also see the use of CONSUME_PRIM_EVENTS Function for rule classes configured for RULE consumption policy
The following commands identify an event that is used for a rule execution and consumes it using its identifier.
var eventid VARCHAR(40);
var evtcnsmd NUMBER;
BEGIN
SELECT rlm$eventid INTO :eventid FROM MatchingPromos WHERE rownum < 2;
-- carry the required action for a rule matched by the above event --
:evtcnsmd := DBMS_RLMGR.CONSUME_EVENT(rule_class => 'TravelPromotion',
event_ident => :eventid);
END;
This function consumes a set of primitive events with all or nothing semantics in the case of a rule class configured with RULE based consumption policy.
DBMS_RLMGR.CONSUME_PRIM_EVENTS ( rule_class IN VARCHAR2, event_idents IN RLM$EVENTIDS) RETURN NUMBER;
Table 88-7 CONSUME_PRIM_EVENTS Function Parameters
| Parameter | Description |
|---|---|
|
|
Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
Event identifiers obtained from the corresponding rule class results view or the arguments of the action callback procedure |
The function returns:
1 -- If all the events, the identifiers for which are passed in, are successfully consumed.
0 -- If one or more primitive event could not be consumed.
When the rule class is configured for RULE based consumption policy, the CONSUME_PRIM_EVENTS function can be used to consume one or more primitive events that constitute a composite event. This operation will succeed only when all the events passed in are still valid and are available for consumption. Any user initiated action should be implemented after checking the return value of the CONSUME_PRIM_EVENTS call.
The following commands show the body of the action callback procedure for a rule class configured for RULE consumption policy. This demonstrates the use of CONSUME_PRIM_EVENTS procedure to consume the events before executing the action for the matched rules.
create or replace procedure PromoAction (
Flt AddFlight,
Flt_EvtId ROWID, --- rowid for the flight primitive event
Car AddRentalCar,
Car_EvtId ROWID,
rlm$rule TravelPromotions%ROWTYPE) is
evtcnsmd NUMBER;
BEGIN
evtcnsmd := DBMS_RLMGR.CONSUME_PRIM_EVENTS(
rule_class => 'TravelPromotions',
event_idents => RLM$EVENTIDS(Flt_EvtId, Car_EvtId));
if (evtcnsmd = 1) then
-- consume operation was successful; perform the action ---
OfferPromotion (Flt.CustId, rlm$rule.PromoType, rlm$rule.OfferedBy);
end if;
END;
This procedure creates an event structure.
DBMS_RLMGR.CREATE_EVENT_STRUCTURE ( event_struct IN VARCHAR2);
Table 88-8 CREATE_EVENT_ STRUCTURE Procedure Parameter
| Parameter | Description |
|---|---|
|
|
Name of the event structure to be created in the current schema |
This procedure creates a dummy the event structure in the current schema. One or more attributes can be added to this event structure using the ADD_ELEMENTARY_ATTRIBUTE procedure.
The following command creates the event structure.
BEGIN DBMS_RLMGR.CREATE_EVENT_STRUCT(event_struct => 'AddFlight'); END;
This procedure creates a rule class.
DBMS_RLMGR.CREATE_RULE_CLASS ( rule_class IN VARCHAR2, event_struct IN VARCHAR2, action_cbk IN VARCHAR2, actprf_spec IN VARCHAR2 default null, rslt_viewnm IN VARCHAR2 default null, rlcls_prop IN VARCHAR2 default <simple/>);
Table 88-9 CREATE_RULE_CLASS Procedure Parameters
| Parameter | Description |
|---|---|
|
|
The name of the rule class to be created in the current schema |
|
|
The name of the object type or an Expression Filter attribute set in the current schema that represents the event structure for the rule class |
|
|
The name of the action callback procedure to be created for the rule class |
|
|
The specification (name and SQL datatype pairs) for the action preferences associated with the rule class |
|
|
The name of the rule class results view that lists the matching events and rules within a session. A view with this name is created in the current schema. |
|
|
The XML document for setting the rule class properties. By default, the rule class created is for simple events (non-composite). |
For successful creation of a rule class, you should have sufficient privileges to create views, object types, tables, packages, and procedures.
This command creates the rule class and its dependent objects in the user's schema. For this operation to succeed the name specified for the event structure should refer to an existing object type or an Expression Filter attribute set in the user's schema. When an object type is used for an event structure, the CREATE_RULE_CLASS procedure implicitly creates an attribute set for the object type. In the case of a rule class configured for composite events, the previous procedure also creates attribute sets for the object types that are directly embedded in the event structure's object type (or the attribute set). A maximum of 32 embedded objects (and/or table aliases) can be specified with an event structure that is used for a composite rule class. The types of dependent objects created with this procedure and their structure depend on the properties of the rule class and its event structure. The minimum set of dependent objects created for a rule class is as follows:
Rule class table – A rule class table that shares the name of the rule class is created in the user's schema to store the rule definitions (rule identifiers, rule conditions, rule descriptions, and action preferences). This table implicitly has three columns, rlm$ruleid, rlm$rulecond, and rlm$ruledesc to store the rule identifiers, rule conditions, and rule descriptions respectively. In addition to these three columns, the rule class table has few columns according to the rule classes' access preference specification. For example, if a TravelPromotion rule class uses 'PromoType VARCHAR(20), OfferedBy VARCHAR(20)' as its access preference specification (assigned to actpref_spec argument), the rule class table is created with the following structure.
TABLE TravelPromotion (
rlm$ruleid VARCHAR(100), -- rule identifier column --
PromoType VARCHAR(20), -- access preference 1 --
OfferedBy VARCHAR(20), -- access preference 2 --
rlm$rulecond VARCHAR(4000), -- rule condition –-
rlm$ruledesc VARCHAR(1000)); -- rule description --
The rule class table structure varies from one rule class to another based on the exact list of action preference categories specified for the rule class.
Action Callback Procedure – The skeleton for the action callback procedure with the given name is created in the user's schema and it is associated with the rule class. During rule evaluation, the callback procedure is called for each matching rule and event. You should implement the body of the action callback procedure to perform the appropriate action for each rule. The exact action for a rule can be determined based on the event that matched the rule and rule definition along with its action preferences. This information is passed to the action callback procedure through its arguments. Hence, the argument list for the action callback procedure depends on the event structure associated with the rule class and the rule class itself.
In the case of a rule class configured for simple events (<simple/> assigned to the properties of the rule class), the event that matches a rule is passed through a rlm$event argument that is declared to be of the same type as the event structure. Additionally, the rule definitions are passed to the action callback procedure using an rlm$rule argument that is declared as ROWTYPE of the corresponding rule class table. For example, the structure of the PromoAction action callback procedure created for a TravelPromotion rule class configured for a simple (non-composite) AddFlight event structure is as follows:
PROCEDURE PromoAction (rlm$event AddFlight,
rlm$rule TravlePromotion%ROWTYPE);
In the case of a rule class created for composite events (<composite/> assigned to the properties of the rule class), the action callback procedure is created to pass each primitive event as a separate argument. For example, the CompPromoAction action callback procedure created for a rule class CompTravelPromo configured for a composite event with AddFlight and AddRentalCar primitive events are shown as follows:
-- composite event structure --
TYPE TSCompEvent (Flt AddFlight,
Car AddRentalCar);
-- corresponding action callback procedure --
PROCEDURE PromoAction (Flt AddFlight,
Car AddRentalCar,
rlm$rule CompTravelPromo%ROWTYPE)
Rule class results view – A view to display the results from matching some events with rules is created in the same schema as the rule class. By default, this view is created with a system-generated name. Optionally, the rule class creator can specify a name for this view with the rlst_viewnm argument of the CREATE_RULE_CLASS procedure. When the events are added to the rule manager within a rule session using the ADD_EVENT procedure, the list of matching events and rules are displayed in the rule class results view.
The structure of the view defined for the rule class results depends on the event structure and the action preferences configured with the rule class. Minimally, the view has three columns to display the system generated event identifier (rlm$evenetid), the identifier of the rule it matches (rlm$ruleid), and the rule condition (rlm$rulecond). Additionally, it has columns to display the event information and the rule action preferences.
In the case of a rule class configured for simple events, the event information is displayed as rlm$event that is declared to be of the event structure type. So, a MatchingPromos view created for the TravelPromotion rule class configured for a simple AddFlight event structure is as follows:
VIEW MatchingPromos (
rlm$eventid ROWID,
rlm$event AddFlight,
rlm$ruleid VARCHAR(100),
PromoType VARCHAR(30), -- action preference 1 --
OffredBy VARCHAR(30), -- action preference 2 --
rlm$rulecond VARCHAR(4000),
rlm$ruledesc VARCHAR(1000)
);
In the case of a rule class configured for composite events, the primitive events matching a rule are displayed separately using corresponding columns. For the above CompTravelPromo rule class, a MatchingCompPromos view is created with the following structure.
VIEW MatchingCompPromos (
rlm$eventid ROWID,
Flt AddFlight,
Car AddRentalCar,
rlm$ruleid VARCHAR(100),
PromoType VARCHAR(30), -- action preference 1 --
OffredBy VARCHAR(30), -- action preference 2 --
rlm$rulecond VARCHAR(4000),
rlm$ruledesc VARCHAR(1000)
);
The values from the rlm$eventid column are used to enforce rule class consumption policies when the corresponding rule is executed. See the CONSUME_EVENT Function procedure for more information.
The following commands create a rule class for simple events (of AddFlight type).
CREATE or REPLACE TYPE AddFlight AS OBJECT (
CustId NUMBER,
Airline VARCHAR(20),
FromCity VARCHAR(30),
ToCity VARCHAR(30),
Depart DATE,
Return DATE);
BEGIN
DBMS_RLMGR.CREATE_RULE_CLASS (
rule_class => 'TravelPromotion', -- rule class name --
event_struct => 'AddFlight', -- event struct name --
action_cbk => 'PromoAction', -- callback proc name –-
rslt_viewnm => 'MatchingPromos', -- results view --
actprf_spec => 'PromoType VARCHAR(20),
OfferedBy VARCHAR(20)');
END;
The following commands create a rule class for composite events consisting of two primitive events (AddFlight and AddRentalCar).
CREATE or REPLACE TYPE TSCompEvent (Flt AddFlight,
Car AddRentalCar);
BEGIN
DBMS_RLMGR.CREATE_RULE_CLASS (
rule_class => 'CompTravelPromo', -- rule class name --
event_struct => 'TSCompEvent', -- event struct name --
action_cbk => 'CompPromoAction', -- callback proc name –-
rslt_viewnm => 'MatchingCompPromos', -- results view --
actprf_spec => 'PromoType VARCHAR(20),
OfferedBy VARCHAR(20)',
properties => '<composite/>');
END;
This procedure deletes a rule from a rule class.
DBMS_RLMGR.DELETE_RULE ( rule_class IN VARCHAR2, rule_id IN VARCHAR2);
Table 88-10 DELETE_RULE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
Name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
Identifier for the rule to be deleted |
This procedure is used to delete a rule from the rule class. The identifier for the rule to be deleted can be obtained by querying the rule class table (that shares the same name as the rule class). Alternately, the owner of the rule class can use a SQL DELETE statement on one rule class table to delete a rule.When schema extended name is used for the rule class, you should have DELETE RULE privilege on the rule class. See the GRANT_PRIVILEGE Procedure procedure for more information.
Note:
AUTOCOMMIT property of the rule class is ignored if the rules are deleted with the SQL DELETE statement instead of the DELETE_RULE procedure.See the CREATE_RULE_CLASS Procedure procedure for the structure of the rule class table.
The following command deletes a rule from the rule class.
BEGIN
DBMS_RLMGR.DELETE_RULE (
rule_class => 'CompTravelPromo',
rule_id => 'AB_AV_FL');
END;
Alternately, the following SQL DELETE statement can be issued to delete the above rule from the rule class.
DELETE FROM CompTravelPromo WHERE rlm$ruleid = 'AB_AV_FL';
This procedure drops an event structure.
DBMS_RLMGR.DROP_EVENT_STRUCTURE ( event_struct IN VARCHAR2);
Table 88-11 DROP_EVENT_ STRUCTURE Procedure Parameter
| Parameter | Description |
|---|---|
|
|
Name of the event structure in the current schema |
This procedure drops the event structure from the current schema. This drops all the dependent objects created to manage the event structure.
The following command drops the event structure.
BEGIN DBMS_RLMGR.DROP_EVENT_STRUCT(event_struct => 'AddFlight'); END;
This procedure drops a rule class.
DBMS_RLMGR.DROP_RULE_CLASS ( rule_class IN VARCHAR2);
Table 88-12 DROP_RULE_CLASS Procedure Parameter
| Parameter | Description |
|---|---|
|
|
The name of the rule class in the current schema |
This procedure drops the rule class from the current schema. This drops all the dependent objects created to manage the rule class. Because an event structure in a user's schema can be shared across multiple rule classes, the event structure is not dropped with this command. The DROP_EVENT_STRUCTURE API should be used for the composite event as well as the individual primitive events to cleanup unused event structures.
The following command drops the rule class.
BEGIN DBMS_RLMGR.DROP_RULE_CLASS(rule_class => 'CompTravelPromo'); END;
This procedure grants privileges on a rule class to another user.
DBMS_RLMGR.GRANT_PRIVILEGE ( rule_class IN VARCHAR2, priv_type IN VARCHAR2, to_user IN VARCHAR2);
Table 88-13 GRANT_PRIVILEGE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
The name of the rule class in the current schema |
|
|
Type of rule class privilege to be granted |
|
|
The user to whom the privilege is to be granted |
This procedure grants appropriate privileges to a user who is not the owner of the rule class. The types of privileges that can be granted to a user are:
PROCESS RULES: A user with PROCESS RULES privilege on a rule class can process the rules in the rule class using the PROCESS_RULES procedure or the ADD_EVENT procedure. Also, the user with this privilege can select from the corresponding rule class results view.
ADD RULE: A user with ADD RULE privilege on a rule class can add rules to a rule class. Alternatively, the owner of the rule class can grant INSERT privileges on one rule class table to other users.
DELETE RULE: A user with DELETE RULE privilege on a rule class can delete rules from a rule class. Alternatively, the owner of the rule class can grant DELETE privileges on one rule class table to other users.
ALL: Granting the ALL privilege on a rule class is equivalent to granting all the above privileges on the rule class to the user.
The owner of the rule class always has privileges to drop a rule class, process rules in a rule class, add rules and delete rules from a rules class. Only the owner of the rule class can drop a rule class and this privilege cannot be granted to another user.
A user should also have EXECUTE privileges on the primitive event types associated with a rule class in order to make use of the corresponding rule class results view
The following command grants PROCESS RULES privilege on TravelPromo rule class to the user SCOTT.
BEGIN
DBMS_RLMGR.GRANT_PRIVILEGE(rule_class => 'TravelPromo',
priv_type => 'PROCESS RULES',
to_user => 'SCOTT');
END;
This procedure processes the rules for a given event. The procedure is overloaded. The different functionality of each form of syntax is presented along with the definitions.
Processes the rules for a string representation of the event instance being added to the rule class:
DBMS_RLMGR.PROCESS_RULES ( rule_class IN VARCHAR2, event_inst IN VARCHAR2, event_type IN VARCHAR2 default null);
Processes the rules for an AnyData representation of the event instance being added to the rule class:
DBMS_RLMGR.PROCESS_RULES ( rule_class IN VARCHAR2, event_inst IN sys.AnyData);
Table 88-14 PROCESS_RULES Procedure Parameters
| Parameter | Description |
|---|---|
|
|
The name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
|
|
String or AnyData representation of the event instance being added to the rule class |
|
|
Type of event instance assigned to the |
This procedure is used to process the rules in a rule class for an event instance assigned to the event_inst argument.
In the case of a rule class configured for simple events (non-composite), the event instance is an instantiation of the corresponding event structure. The rules are evaluated (conclusively) for this event and the corresponding action callback procedure is called for each matching rule. If the event does not match any rule, no further action is performed. If the event matches two or more rules, the ordering clause configured for the rule class is used to order them accordingly to invoke the action callback procedure. If the rule class is configured for EXCLUSIVE consumption policy, once the first rule in this order is executed (and the corresponding action callback procedure is called), the rest of the rules that matched the event are ignored.
In the case of a rule class configured for composite events, the event instance assigned to the event_inst argument is an instantiation of one of the primitive type within the composite event. When the instance is represented as a string, the corresponding type name should be assigned to the event_type argument. The PROCESS_RULES call on a rule class configured for composite events performs various actions depending on the state of the rule class and the kind of rules in the rule class.
The rules operating only on the primitive event passed in are evaluated conclusively and the action callback procedure is called for the matching rules, as described in previous paragraph.
In the case of a rule operating on more than one primitive event, the event instance passed through PROCESS_RULES procedure could match only a part of the rule.
If there is (are) another primitive event instance(s) that matches the rest of the rule, the current event instance is combined with the other instance(s) to form a complete composite event that matches a rule in the rule class. So, the event instance assigned to the event_inst argument of the PROCESS_RULES procedure could be combined with various other primitive events (previously processed) to evaluate one or more rules conclusively. The rule classes' action callback procedure is called for each such combination of primitive events (composite event) and the rule. The ordering clause for the rule class and the consumption policy for the primitive events in taken into account while invoking the action callback procedure.
If there is no other primitive event that matches the rest of the rule, the current event instance and its (incremental) evaluation results are recorded in the database. These results are preserved until either the event is consumed or deleted from the system owing to the duration policy used for the rule class.
The following command processes the rules in the TravelPromotion rule class for the given events.
BEGIN
DBMS_RLMGR.PROCESS_RULES (
rule_class => 'TravelPromotion',
event_inst =>
AddFlight.getVarchar(987, 'Abcair', 'Boston', 'Orlando',
'01-APR-2003', '08-APR-2003'));
END;
The following commands process the rules in the CompTravelPromo rule class for the two primitive events shown.
BEGIN DBMS_RLMGR.PROCESS_RULES(
rule_class => 'CompTravelPromo',
event_inst =>
AddFlight.getVarchar(987, 'Abcair', 'Boston', 'Orlando',
'01-APR-2003', '08-APR-2003'),
event_type => 'AddFlight');
DBMS_RLMGR.PROCESS_RULES(
rule_class => 'Scott.CompTravelPromo',
event_inst =>
AnyData.convertObject(AddRentalCar(987, 'Luxury', '03-APR-2003',
'08-APR-2003', NULL)));
END;
This procedure starts a new session and thus discards the results in the rule class results view.
DBMS_RLMGR.RESET_SESSION ( rule_class IN VARCHAR2);
Table 88-15 RESET_SESSION Procedure Parameter
| Parameter | Description |
|---|---|
|
|
The name of the rule class. A schema extended rule class name can be used to refer to a rule class that does not belong to the current schema. |
When the ADD_EVENT procedure is used to add events to the rule class, the results from matching rules with events are recorded in the rule class results view. By default, these results are reset at the end of the database session. Alternately, the RESET_SESSION Procedure can be used to reset and start a new rule session within a database session.
This procedure is only applicable while using ADD_EVENT Procedures to evaluate the rules.
The following command resets a rule class session.
BEGIN DBMS_RLMGR.RESET_SESSION(
rule_class => 'CompTravelPromo');
END;
This procedure revokes privileges on a rule class from another user.
DBMS_RLMGR.REVOKE_PRIVILEGE ( rule_class IN VARCHAR2, priv_type IN VARCHAR2, from_user IN VARCHAR2);
Table 88-16 REVOKE_PRIVILEGE Procedure Parameters
| Parameter | Description |
|---|---|
|
|
The name of the rule class in the current schema |
|
|
Type of rule class privilege to be revoked |
|
|
The user from whom the privilege is to be revoked |
This procedure revokes appropriate privileges from a user. The types of privileges that can be revoked are the same as the types listed in the GRANT_PRIVILEGE Procedure description. Rule class privileges cannot be revoked from the owner of the rule class.
The following command revokes PROCESS RULES privilege on TravelPromo rule class from the user SCOTT.
BEGIN
DBMS_RLMGR.REVOKE_PRIVILEGE(rule_class => 'TravelPromo',
priv_type => 'PROCESS RULES',
from_user => 'SCOTT');
END;