cosNotification
User's Guide
Version 1.2.2

Chapters

• The cosNotification Application
  • Top of chapter
  • Content Overview
  • Brief Description of the User's Guide
• Introduction to cosNotification
  • Top of chapter
  • Overview
• Installing cosNotification
  • Top of chapter
  • Installation Process
• The Notification Service Components
  • Top of chapter
  • The Notification Service Components
• Filters and the Constraint Language BNF
  • Top of chapter
  • Filters and the Constraint Language BNF
• Quality Of Service and Admin Properties
  • Top of chapter
  • Quality Of Service and Admin Properties
• cosNotification Examples
  • Top of chapter
  • A Tutorial on How to Create a Simple Service

5 Filters and the Constraint Language BNF

5.1  Filters and the Constraint Language BNF

This chapter describes, the grammar supported by CosNotifyFilter_Filter and CosNotifyFilter_MappingFilter, and how to create and use filter objects.

How to create filter objects

To be able to filter events we must create a filter and associate it with one, or more, of the administrative or proxy objects. In the example below, we choose to associate the filter with a ConsumerAdmin object.

FilterFactory = cosNotificationApp:start_filter_factory(),
Filter = 'CosNotifyFilter_FilterFactory':
                     create_filter(FilterFactory,"EXTENDED_TCL"),
ConstraintInfoSeq = 'CosNotifyFilter_Filter':
                     add_constraints(Filter, ConstraintExpSeq),
FilterID = 'CosNotifyChannelAdmin_ConsumerAdmin':
                     add_filter(AdminConsumer, Filter),
      

"EXTENDED_TCL" is the only grammar supported by Orber Notification Service.

Depending on which operation type the Admin object uses, i.e., 'AND_OP' or 'OR_OP', events will be tested using the associated filter. The operation properties are:

• 'AND_OP' - must be approved by the proxy's and its parent admin's filters. If all filters associated with an object (Admin or Proxy) return false the event will be discarded. In this situation it is pointless to try and verify with the other object's associated filters since the outcome still would be the same.

• 'OR_OP' - if one of the object's (Admin or Proxy) filters return true, the event will not be checked against any other filter associated with a proxy or its parent admin. If a object's associated filters all return false, the event will be forwarded to related proxies/admins, and tested against any associated filters.

Initially, filters are empty and will always return true. Hence, we must add constraints by using 'CosNotifyFilter_Filter':add_constraints/2. As input, the second argument must be a sequence of:

#'CosNotifyFilter_ConstraintExp'{
       event_types = [#'CosNotification_EventType'{
                             domain_name = string(),
                             type_name = string()}], 
       constraint_expr = string()}
      

The event_types describes which types of events that should be matched using the associated constraint_expr.

If a constraint expression is supposed to apply for all events, then the type_name can be set to the special event type %ALL in a constraint's event type sequence. The domain_name should be "" or "*".

In the following sections we will take a closer look on how to write constraint expressions.

The CosNotification Constraint Language

The constraint language supported by the Notification Service is:

<constraint> := /* empty */ 
    | <bool> 

<bool> := <bool_or> 

<bool_or> := <bool_or> or <bool_and> 
    | <bool_and> 

<bool_and> := <bool_and> and <bool_compare> 
    | <bool_compare> 

<bool_compare> := <expr_in> == <expr_in> 
    | <expr_in> != <expr_in> 
    | <expr_in> < <expr_in> 
    | <expr_in> <= <expr_in>
    | <expr_in> > <expr_in> 
    | <expr_in> >= <expr_in> 
    | <expr_in> 

<expr_in> := <expr_twiddle> in <Ident> /* sequence only */
    | <expr_twiddle> 
    | <expr_twiddle> in $ <Component> /* sequence only */

<expr_twiddle> := <expr> ~ <expr> /* string data types only */
    | <expr> 

<expr> := <expr> + <term> 
    | <expr> - <term> 
    | <term> 

<term> := <term> * <factor_not> 
    | <term> / <factor_not> 
    | <factor_not> 

<factor_not> := not <factor> 
    | <factor> 

<factor> := ( <bool_or> ) 
    | exist <Ident> 
    | <Ident> 
    | <Number> 
    | - <Number> 
    | <String> 
    | TRUE 
    | FALSE
    | + <Number> 
    | exist $ <Component> 
    | $ <Component> 
    | default $ <Component> /* discriminated unions only */

<Component> := /* empty */ 
    | . <CompDot> 
    | <CompArray> 
    | <CompAssoc> 
    | <Ident> <CompExt> /* run-time variable */ 

<CompExt> := /* empty */ 
    | . <CompDot> 
    | <CompArray> 
    | <CompAssoc> 

<CompDot> := <Ident> <CompExt> 
    | <CompPos> 
    | <UnionPos> 
    | _length   /* only valid for arrays or sequences */
    | _d        /* discriminated unions only */
    | _type_id  /* only valid if possible to obtain */
    | _repos_id /* only valid if possible to obtain */

<CompArray> := [ <Digits> ] <CompExt> 

<CompAssoc> := ( <Ident> ) <CompExt> 

<CompPos> := <Digits> <CompExt>

<UnionPos> := ( <UnionVal> ) <CompExt> 

<UnionVal> := /* empty */ 
    | <Digits> 
    | - <Digits> 
    | + <Digits> 
    | <String>

/* Character set issues */
<Ident> :=<Leader> <FollowSeq> 
    | \ < Leader> <FollowSeq>

<FollowSeq> := /* <empty> */ 
    | <FollowSeq> <Follow> 

<Number> := <Mantissa> 
    | <Mantissa> <Exponent>

<Mantissa> := <Digits> 
    | <Digits> . 
    | . <Digits> 
    | <Digits> . <Digits> 

<Exponent> := <Exp> <Sign> <Digits> 

<Sign> := + 
    | -

<Exp> := E 
    | e 

<Digits> := <Digits> <Digit> 
    | <Digit> 

<String> := ' <TextChars> '   

<TextChars> := /* <empty> */ 
    | <TextChars> <TextChar> 

<TextChar> := <Alpha> 
    | <Digit> 
    | <Other> 
    | <Special> 

<Special> := \\ 
    | \' 

<Leader> := <Alpha>

<Follow> := <Alpha> 
    | <Digit> 
    | _

<Alpha> is the set of alphabetic characters [A-Za-z] 
<Digit> is the set of digits [0-9] 
<Other> is the set of ASCII characters that are not <Alpha>, <Digit>, or <Special>
      

In the absence of parentheses, the following precedence relations hold :

• (), exist, default, unary-sign
• not
• *, /
• +, -
• ~
• in
• ==, !=, <, <=, >, >=
• and
• or

The Constraint Language Data Types

The Notification Service Constraint Language, defines how to write constraint expressions, which can be used to filter events. The representation does, however, differ slightly from ordinary Erlang terms.

When creating a ConstraintExp, the field constraint_expr must be set to contain a string, e.g., "1 < 2". The Notification Service Constraint Language, is designed to be able to filter structured and unstructured events using the same constraint expression. The Constraint Language Types and Operations can be divided into two sub-groups:

• Basic - arithmetics, strings, constants, numbers etc.

• Complex - accessing members of complex data types, such as unions.

Some of the basic types, e.g., integer, are self explanatory. Hence, they are not described further.

In the next section we will take a closer look at how it is possible to write constraints using different types of notation etc.

Accessing Data In Events

To filter events, the supplied constraints must describe the contents of the events and desired values. We can, for example, state that we are only interested in receiving events which are of type CommunicationsAlarm. To be able to achieve this, the constraint must contain information that points out which fields to compare with. Figure one illustrates a conceptual overview of a structured event. The exact definition is found in the CosNotification.idl file.

Figure 5.1:   Figure 1: The structure of a structured event.

The Notification Service supports different constraint expressions notation:

• Fully scoped, e.g., "$.header.fixed_header.event_type.type_name == 'CommunicationsAlarm'"

• Short hand, e.g., "$type_name == 'CommunicationsAlarm'"

• Positional Notation, e.g., "$.0.0.0.1 == 'CommunicationsAlarm'"

How to filter against the fixed header fields, is described in the table below.

If we are only interested in receiving events regarding 'Domain', 'Event' and 'Type', the constraint can look like "$domain_name == 'Domain' and $event_name == 'Event' and $type_name == 'Type'".

The variable event header consists of a sequence of name-value pairs. One way to filter on these are to use a constraint that looks like "($.header.variable_header[1].name == 'priority' and $.header.variable_header[1].value > 0)". An easier way to accomplish the same result is to use a constraint that treats the name-value pair as an associative array, i.e., when given a name the corresponding value is returned. Hence, instead we can use "$.header.variable_header(priority) > 0".

Accessing the event body is done in the same way as for the event header fields. The user must, however, be aware of, that if a run-time variable ($variable) is used data in the event header may take precedence. The order of precedence is:

• Reserved, e.g., $curtime
• A simple-typed member of $.header.fixed_header.
• Properties in $.header.variable_header.
• Properties in $.filterable_data.
• If no match is found it is translated to $.variable.

Mapping Filters

Mapping Filters may only be associated with Consumer Administrators or Proxy Suppliers. The purpose of a Mapping Filter is to override Quality of Service settings.

Initially, Mapping Filters are empty and will always return true. Hence, we must add constraints by using 'CosNotifyFilter_MappingFilter':add_mapping_constraints/2. If a constraint matches, the associated value will be used instead of the related Quality of Service system settings.

As input, the second argument must be a sequence of:

#'CosNotifyFilter_MappingConstraintPair'{
    constraint_expression = #'CosNotifyFilter_ConstraintExp'{
       event_types = [#'CosNotification_EventType'{
                             domain_name = string(),
                             type_name = string()}], 
       constraint_expr = string()},
    result_to_set = any()}