Streams is all about the rules; literally. The action context that a Streams process takes is governed by the rule conditions. When you create a rule, Oracle generates system conditions, and evaluation contexts, that are used to evaluate each LCR to determine if the action context for the process should be accomplished. We have already addressed a number of these system conditions during our TAG discussion; for instance INCLUDE_TAGGED_LCR=FALSE generates a system evaluation for theLCR$_ROW_RECORD_TYPE :dml.is_null_tag=’Y’ subprogram.
For more information on LCR Types, reference Oracle Database PL/SQL Packages and Types Reference manual.
You can control what system evaluations are included in the rule by the parameter values you specify, as well as add user-defined evaluations with the AND_CONDITION parameter.
There is a lot going on under the calm surface water of rules. Understanding how this activity flows together will help you become more advanced in creating rules to manipulate your Streams throughout your current environment. So, let’s grab our snorkels and masks, and stick our heads under the surface and take a look.
Rule components
Rules have three components: conditions, evaluation context, and action context. These components coordinate with the “when”, “what”, and “how” of the LCR being processed. The conditions tell the Streams process “when” the LCR should be processed, the evaluation context defines “what” data/information the Streams process uses to process the LCR, and the action context tells the Streams process “how” to handle the LCR.
Rule conditions
The rule condition is essentially the “where clause”. The conditions are evaluated against the properties of the LCR and return either TRUE or FALSE The conditions can contain compound expressions and operators (AND, OR, NOT, and so on).The final evaluation returned from the condition (TRUE or FALSE) is the final result of all the compound expressions. An example of a system-generated condition would be that of our good friend :dml.is_null_tag = ‘Y’ (generated by the INCLUDE_TAGGED_LCR=FALSE parameter of the DBMS_STREAMS_ADM.ADD_*_RULE procedures). On rule creation, the condition is passed in as a string (so make sure to escape any single quotes within the string).
':dml.get_object_owner() = ''OE'' and :dml.get_tag() =
HEXTORAW(''22'')'
It is important to remember that you want to keep your rule conditions as simple as possible. Complex rule conditions can have a significant impact on performance. The rule condition created by our Sub-Setting example is an example of a complex rule as it includes a PL/SQL call to a function. Also, rule conditions that contain NOT, or != can also impact performance.
Rule Evaluation Context
The rule evaluation context defines data external to the LCR properties that can be referenced in the rule conditions. This is comparable to the SQL statement from clause. This reference is a database object that contains the external data. The evaluation context provides the rule conditions with the necessary information for interpreting and evaluating the conditions that reference external data. If the evaluation context references objects, the rule owner must have the proper privileges to reference the object (select and execute) as the rule condition is evaluated in the schema of the evaluation context owner. Information contained in an Evaluation Context might include table aliases used in the condition, variable names and types, and/or a function to use to evaluate the rules to which the evaluation context is assigned.
Evaluation Context structure can get a bit confusing. To get a better feel of it, you may want to start by looking at the following database views:
- DBA/ALL/USER_EVALUATION_CONTEXT_TABLES: table alias used
- DBA/ALL/USER_EVALUATION_CONTEXT_VARS: variable types used
- DBA/ALL/USER_EVALUATION_CONTEXTS: functions used
Streams system created rules (created using DBMS_STREAMS_ADM) will create rules using the standard Oracle-supplied SYS.STREAMS$_EVALUATION_CONTEXT rule evaluation context. This evaluation context is composed of a variable_types> list for the :dml and :ddl variables, and the evaluation function SYS.DBMS_STREAMS_INTERNAL.EVALUATION_CONTEXT_FUNCTION as seen in the previous DBA views.
You can create your own evaluation context using the DBMS_RULE_ADM.CREATE_EVALUATION_CONTEXT procedure:
DBMS_RULE_ADM.CREATE_EVALUATION_CONTEXT(
evaluation_context_name IN VARCHAR2,
table_aliases IN SYS.RE$TABLE_ALIAS_LIST DEFAULT NULL,
variable_types IN SYS.RE$VARIABLE_TYPE_LIST DEFAULT NULL,
evaluation_function IN VARCHAR2 DEFAULT NULL,
evaluation_context_comment IN VARCHAR2 DEFAULT NULL
);
If you create a custom Evaluation Context that uses the SYS.DBMS_STREAMS_INTERNAL.EVALUATION_CONTEXT_FUNCTION, it must include the same variables and types as in the SYS.STREAMS$_EVALUATION_CONTEXT (a.k.a. :dml and :ddl).
Variable_types> can be defined using SYS.RE$VARIABLE_TYPE_LIST, which in turn accepts individual variable types defined using SYS.RE$VARIABLE_TYPE.
Similarly, if you create a custom function to use as the evaluation function, it must have the following signature:
FUNCTION evaluation_function_name(
rule_set_name IN VARCHAR2,
evaluation_context IN VARCHAR2,
event_context IN SYS.RE$NV_LIST DEFAULT NULL,
table_values IN SYS.RE$TABLE_VALUE_LIST DEFAULT NULL,
column_values IN SYS.RE$COLUMN_VALUE_LIST DEFAULT NULL,
variable_values IN SYS.RE$VARIABLE_VALUE_LIST DEFAULT NULL,
attribute_values IN SYS.RE$ATTRIBUTE_VALUE_LIST DEFAULT NULL,
stop_on_first_hit IN BOOLEAN DEFAULT FALSE,
simple_rules_only IN BOOLEAN DEFAULT FALSE,
true_rules OUT SYS.RE$RULE_HIT_LIST,
maybe_rules OUT SYS.RE$RULE_HIT_LIST);
RETURN BINARY_INTEGER;
Where the returned BINARY_INTEGER value must be one of the following:
DBMS_RULE_ADM.EVALUATION_SUCCESS
DBMS_RULE_ADM.EVALUATION_CONTINUE
DBMS_RULE_ADM.EVALUATION_FAILURE
For more information on creating custom Evaluation Contexts and evaluation functions and Rule Types, refer to the Oracle Database PL/SQL Packages and Types Reference manual, and The Oracle Streams Extended Examples manual.
Once an Evaluation Context is created it can be assigned to a rule or a rule set using the evaluation_context parameter of the appropriate DBMS_RULE_ADM procedure.
The Evaluation Context for a Rule can be different than the Evaluation Context for a Rule Set to which the Rule might be assigned. The bottom line is that a Rule must be able to associate itself with an Evaluation Context at some level. We will revisit this concept as we discuss Rule Creation a little later on this section.
Action Context
The rule action context is just that, the action information that the rule evaluation engine returns to the client application, to be acted upon by the client application, when the rule evaluates to true. This is not the action itself, but values to be used by the action code that are specific to the rule. The action context is of the SYS.RE$NV_LIST type, which contains an array of name-value pairs and is associated to a rule condition. A rule condition can only have one action context. The action context itself is optional and can contain zero to many name-value pairs.
The SYS.RE$NV_LIST has the following construct:
TYPE SYS.RE$NV_LIST AS OBJECT(
actx_list SYS.RE$NV_ARRAY);
Subprograms are:
ADD_PAIR (name IN VARCHAR2,
value IN ANYDATA);
GET_ALL_NAMES ()
RETURN SYS.RE$NAME_ARRAY;
GET_VALUE (name IN VARCHAR2)
RETURN ANYDATA;
REMOVE_PAIR (name IN VARCHAR2);
For more information on creating and populating Action Contexts types, refer to the Oracle Database PL/SQL Packages and Types Reference manual.
For more information on Rule components refer to the Oracle Streams Concepts and Administration manual.