<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- Filters and the Constraint Language BNF</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/cosNotification-1.1.18.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>cosNotification</strong><br><strong>User's Guide</strong><br><small>Version 1.1.18</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Chapters</strong></small></p>
<ul class="flipMenu" imagepath="../../../../doc/js/flipmenu">
<li id="no" title="The cosNotification Application" expanded="false">The cosNotification Application<ul>
<li><a href="ch-contents.html">
Top of chapter
</a></li>
<li title="Content Overview"><a href="ch-contents.html#id63553">Content Overview</a></li>
<li title="Brief Description of the User's Guide"><a href="ch-contents.html#id57496">Brief Description of the User's Guide</a></li>
</ul>
</li>
<li id="no" title="Introduction to cosNotification" expanded="false">Introduction to cosNotification<ul>
<li><a href="ch_introduction.html">
Top of chapter
</a></li>
<li title="Overview"><a href="ch_introduction.html#id59810">Overview</a></li>
</ul>
</li>
<li id="no" title="Installing cosNotification" expanded="false">Installing cosNotification<ul>
<li><a href="ch-install.html">
Top of chapter
</a></li>
<li title="Installation Process "><a href="ch-install.html#id61483">Installation Process </a></li>
</ul>
</li>
<li id="no" title="The Notification Service Components" expanded="false">The Notification Service Components<ul>
<li><a href="ch_system.html">
Top of chapter
</a></li>
<li title="The Notification Service Components"><a href="ch_system.html#id62962">The Notification Service Components</a></li>
</ul>
</li>
<li id="loadscrollpos" title="Filters and the Constraint Language BNF" expanded="true">Filters and the Constraint Language BNF<ul>
<li><a href="ch_BNF.html">
Top of chapter
</a></li>
<li title="Filters and the Constraint Language BNF"><a href="ch_BNF.html#id64314">Filters and the Constraint Language BNF</a></li>
</ul>
</li>
<li id="no" title="Quality Of Service and Admin Properties" expanded="false">Quality Of Service and Admin Properties<ul>
<li><a href="ch_QoS.html">
Top of chapter
</a></li>
<li title="Quality Of Service and Admin Properties"><a href="ch_QoS.html#id65103">Quality Of Service and Admin Properties</a></li>
</ul>
</li>
<li id="no" title="cosNotification Examples" expanded="false">cosNotification Examples<ul>
<li><a href="ch_example.html">
Top of chapter
</a></li>
<li title="A Tutorial on How to Create a Simple Service"><a href="ch_example.html#id65997">A Tutorial on How to Create a Simple Service</a></li>
</ul>
</li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<h1>5 Filters and the Constraint Language BNF</h1>
<h3><a name="id64314">5.1
Filters and the Constraint Language BNF</a></h3>
<p>This chapter describes, the grammar supported by
<span class="bold_code"><a href="CosNotifyFilter_Filter.html">CosNotifyFilter_Filter</a></span> and
<span class="bold_code"><a href="CosNotifyFilter_MappingFilter.html">CosNotifyFilter_MappingFilter</a></span>,
and how to create and use filter objects.
</p>
<h4>How to create filter objects</h4>
<p>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.</p>
<div class="example"><pre>
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),
</pre></div>
<p><span class="code">"EXTENDED_TCL"</span> is the only grammar supported by Orber Notification
Service.</p>
<p>Depending on which operation type the Admin object uses, i.e.,
<span class="code">'AND_OP'</span> or <span class="code">'OR_OP'</span>, events will be tested using the
associated filter. The operation properties are:</p>
<p></p>
<ul>
<li>
<p>'AND_OP' - must be approved by the proxy's <strong>and</strong> 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.</p>
</li>
<li>
<p>'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.</p>
</li>
</ul>
<p>Initially, filters are empty and will always return true. Hence, we must
add constraints by using <span class="code">'CosNotifyFilter_Filter':add_constraints/2</span>.
As input, the second argument must be a sequence of:</p>
<div class="example"><pre>
#'CosNotifyFilter_ConstraintExp'{
event_types = [#'CosNotification_EventType'{
domain_name = string(),
type_name = string()}],
constraint_expr = string()}
</pre></div>
<p>The <span class="code">event_types</span> describes which types of events that should be matched using
the associated <span class="code">constraint_expr</span>.</p>
<p>If a constraint expression is supposed to apply for all events, then the <span class="code">type_name</span> can
be set to the special event type <span class="code">%ALL</span> in a constraint's event type sequence. The
<span class="code">domain_name</span> should be <span class="code">""</span> or <span class="code">"*"</span>.</p>
<p>In the following sections we will take a closer look on how to write
constraint expressions.</p>
<h4>The CosNotification Constraint Language</h4>
<p>The constraint language supported by the Notification Service is:</p>
<div class="example"><pre>
<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>
</pre></div>
<p>In the absence of parentheses, the following precedence relations hold :</p>
<ul>
<li>
<span class="code">()</span>, <span class="code">exist</span>, <span class="code">default</span>, <span class="code">unary-sign</span>
</li>
<li><span class="code">not</span></li>
<li>
<span class="code">*</span>, <span class="code">/</span>
</li>
<li>
<span class="code">+</span>, <span class="code">-</span>
</li>
<li><span class="code">~</span></li>
<li><span class="code">in</span></li>
<li>
<span class="code">==</span>, <span class="code">!=</span>, <span class="code"><</span>, <span class="code"><=</span>, <span class="code">></span>, <span class="code">>=</span>
</li>
<li><span class="code">and</span></li>
<li><span class="code">or</span></li>
</ul>
<h4>The Constraint Language Data Types</h4>
<p>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.</p>
<p>When creating a <span class="code">ConstraintExp</span>, the field <span class="code">constraint_expr</span> must be
set to contain a string, e.g., <span class="code">"1 < 2"</span>. 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:</p>
<ul>
<li>
<p>Basic - arithmetics, strings, constants, numbers etc.</p>
</li>
<li>
<p>Complex - accessing members of complex data types, such as unions.</p>
</li>
</ul>
<p>Some of the basic types, e.g., integer, are self explanatory. Hence, they are not described further.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle"><strong>Type/Operation</strong></td>
<td align="left" valign="middle"><strong>Examples</strong></td>
<td align="left" valign="middle"><strong>Description</strong></td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">string</span></td>
<td align="left" valign="middle"><span class="code">"'MyString'"</span></td>
<td align="left" valign="middle">Strings are represented as a sequence of zero or more <span class="code"><TextChar></span>s enclosed in single quotes, e.g., <span class="code">'string'</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">~</span></td>
<td align="left" valign="middle"><span class="code">"'Sring1' ~ 'String2'"</span></td>
<td align="left" valign="middle">The operator <span class="code">~</span>is called the substring operator and mean "String1 is contained within String2".</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">boolean</span></td>
<td align="left" valign="middle"><span class="code">"TRUE == (('lang' ~ 'Erlang' + 'fun' ~ 'functional') >= 2)"</span></td>
<td align="left" valign="middle">Booleans may only be TRUE or FALSE, i.e., only capital letters. Expressions which evaluate to TRUE or FALSE can be summed up and matched, where TRUE equals 1 and FALSE 0.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">sequence</span></td>
<td align="left" valign="middle"><span class="code">"myIntegerSequence[2]"</span></td>
<td align="left" valign="middle">The BNF use C/C++ notation, i.e., the example will return the <strong>third</strong>element.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">_length</span></td>
<td align="left" valign="middle"><span class="code">"myIntegerSequence._length"</span></td>
<td align="left" valign="middle">Returns the length of an sequence or array.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">in</span></td>
<td align="left" valign="middle"><span class="code">"'Erlang' in $.FunctionalLanguagesStringSeq"</span></td>
<td align="left" valign="middle">Returns <span class="code">TRUE</span>if a given element is found in the given sequence. The element must be of a simple type and the same as the sequence is defined to contain.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">$</span></td>
<td align="left" valign="middle"><span class="code">"$ == 40"</span></td>
<td align="left" valign="middle">Denote the current event as well as any run-time variables. If the event is unstructured and its contained value 40, the example will return <span class="code">TRUE</span>.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">.</span></td>
<td align="left" valign="middle"><span class="code">"$.MyStructMember == 40"</span></td>
<td align="left" valign="middle">The structure member operator <span class="code">.</span>may be used to reference its members when the data refers to a named structure, discriminated union, or CORBA::Any data structure.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">_type_id</span></td>
<td align="left" valign="middle"><span class="code">"$._type_id == 'MyStruct'"</span></td>
<td align="left" valign="middle">Returns the unscoped IDL type name of the component. This operation is only valid if said information can be obtained.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">_repos_id</span></td>
<td align="left" valign="middle"><span class="code">"$._repos_id == 'IDL:MyModule/MyStruct:1.0'"</span></td>
<td align="left" valign="middle">Returns the RepositoryId of the component. This operation is only valid if said information can be obtained.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">_d</span></td>
<td align="left" valign="middle"><span class="code">"$.eventUnion._d"</span></td>
<td align="left" valign="middle">May only be used when accessing discriminated unions and refers to the discriminator.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">exist</span></td>
<td align="left" valign="middle"><span class="code">"exist $.eventUnion._d and $.eventUnion._d == 10"</span></td>
<td align="left" valign="middle">To avoid that a filtering of an event fails due to that, for example, we try to compare a union discriminator which does not exist, we can use this operator.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">default</span></td>
<td align="left" valign="middle"><span class="code">"default $.eventUnion._d"</span></td>
<td align="left" valign="middle">If the <span class="code">_d</span>operation is in conjunction with the <span class="code">default</span>operation, TRUE will be returned if the union has a default member that is active.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">union</span></td>
<td align="left" valign="middle">
<span class="code">"$.(0) == 5"</span>eq. <span class="code">"$.('zero') == 5"</span>
</td>
<td align="left" valign="middle">When the component refers to a union, with one of the cases defined as <span class="code">case 0: short zero;</span>, we use <span class="code">0</span>or <span class="code">'zero'</span>. The result of the example is <span class="code">TRUE</span>if the union has a discriminator set to <span class="code">0</span>and the value <span class="code">5</span>. If more than one case is defined to be<span class="code">'zero'</span>, <span class="code">$.('zero')</span>accepts both; <span class="code">$.(0)</span>only returns <span class="code">TRUE</span>if the discriminator is set to <span class="code">0</span>. Leaving out the identifier, i.e., <span class="code">$.()</span>, refers to the default value.</td>
</tr>
<tr>
<td align="left" valign="middle"><span class="code">name-value pairs</span></td>
<td align="left" valign="middle">
<span class="code">"$.NameValueSeq('myID') == 5"</span>eq.<span class="code">"$.NameValueSeq[1].name == 'myID' and $.NameValueSeq[1].value == 5"</span>
</td>
<td align="left" valign="middle">The Notification service makes extensive use of <span class="code">name-value pairs</span>sequences within structured events, which allow us to via the identifier <span class="code">name</span>access its <span class="code">value</span>, as shown in the example.</td>
</tr>
</table>
<em>Table
5.1:
Table 1: Type and Operator Examples</em>
<p>In the next section we will take a closer look at how it is possible to write constraints using
different types of notation etc.</p>
<h4>Accessing Data In Events</h4>
<p>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 <strong>CommunicationsAlarm</strong>.
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 <span class="code">CosNotification.idl</span> file.</p>
<a name="eventstructure"></a>
<img alt="IMAGE MISSING" src="eventstructure.gif"><br>
<em>Figure
5.1:
Figure 1: The structure of a structured event.</em>
<p>The Notification Service supports different constraint expressions
notation:</p>
<ul>
<li>
<p>Fully scoped, e.g., "$.header.fixed_header.event_type.type_name == 'CommunicationsAlarm'"</p>
</li>
<li>
<p>Short hand, e.g., "$type_name == 'CommunicationsAlarm'"</p>
</li>
<li>
<p>Positional Notation, e.g., "$.0.0.0.1 == 'CommunicationsAlarm'"</p>
</li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Which notation to use is up to the user, however, the fully scoped may
be easier to understand, but in some cases, if received from an ORB that do not populate ID:s of
named parts, the positional notation is the only option.</p>
</p></div>
</div>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>If a constraint, which access fields in a structured event structure,
is supposed to handle unstructured events as well, the CORBA::Any must contain
the same type of members.</p>
</p></div>
</div>
<p>How to filter against the fixed header fields, is described in the
table below.</p>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td align="left" valign="middle">Field</td>
<td align="left" valign="middle">Fully Scoped Constraint</td>
<td align="left" valign="middle">Short Hand Constraint</td>
</tr>
<tr>
<td align="left" valign="middle">type_name</td>
<td align="left" valign="middle">"$.header.fixed_header.event_type.type_name == 'Type'"</td>
<td align="left" valign="middle">"$type_name == 'Type'"</td>
</tr>
<tr>
<td align="left" valign="middle">domain_name</td>
<td align="left" valign="middle">"$.header.fixed_header.event_type.domain_name == 'Domain'"</td>
<td align="left" valign="middle">"$domain_name == 'Domain'"</td>
</tr>
<tr>
<td align="left" valign="middle">event_name</td>
<td align="left" valign="middle">"$.header.fixed_header.event_name == 'Event'"</td>
<td align="left" valign="middle">"$event_name == 'Event'"</td>
</tr>
</table>
<em>Table
5.2:
Table 2: Fixed Header Constraint Examples</em>
<p>If we are only interested in receiving events regarding 'Domain', 'Event'
and 'Type', the constraint can look like
<span class="code">"$domain_name == 'Domain' and $event_name == 'Event' and $type_name == 'Type'"</span>.</p>
<p>The variable event header consists of a sequence of <strong>name-value pairs</strong>. One way to filter on these are to use a constraint that looks
like <span class="code">"($.header.variable_header[1].name == 'priority' and $.header.variable_header[1].value > 0)"</span>. 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
<span class="code">"$.header.variable_header(priority) > 0"</span>.</p>
<p>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
(<span class="code">$variable</span>) is used data in the event header may take precedence.
The order of precedence is:</p>
<ul>
<li>Reserved, e.g., <span class="code">$curtime</span>
</li>
<li>A simple-typed member of <span class="code">$.header.fixed_header</span>.</li>
<li>Properties in <span class="code">$.header.variable_header</span>.</li>
<li>Properties in <span class="code">$.filterable_data</span>.</li>
<li>If no match is found it is translated to <span class="code">$.variable</span>.</li>
</ul>
<h4>Mapping Filters</h4>
<p>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.</p>
<p>Initially, Mapping Filters are empty and will always return true. Hence, we must
add constraints by using <span class="code">'CosNotifyFilter_MappingFilter':add_mapping_constraints/2</span>.
If a constraint matches, the associated value will be used instead of the
related Quality of Service system settings.</p>
<p>As input, the second argument must be a sequence of:</p>
<div class="example"><pre>
#'CosNotifyFilter_MappingConstraintPair'{
constraint_expression = #'CosNotifyFilter_ConstraintExp'{
event_types = [#'CosNotification_EventType'{
domain_name = string(),
type_name = string()}],
constraint_expr = string()},
result_to_set = any()}
</pre></div>
</div>
<div class="footer">
<hr>
<p>Copyright © 2000-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
382
