Class Index | File Index

Classes


Namespace Selector

Event Selectors

Event Selectors are a way of selectively filtering events by criteria stored in the header fields and user-defined properties of an Event Datagram. Only events whose header and property values match the selector are delivered to the event consumer.

The application fabric optimizes selector performance by pushing match logic execution into the dispatcher of the event producer. This technique ensures that only events in which consumers have registered an interest are actually raised. Dispatcher based filtering is extremely efficient, capable of processing hundreds of thousands of events per second without significant impact on throughput or latency of the system.

The selector is an extension of the Message Selector capability as outlined in the Java Messaging Service (JMS) specification. Similar to JMS an event selector is a String whose syntax is based on a subset of the SQL-92 conditional expression syntax with several notable differences.
   – Event Selectors support advanced date comparison and date range arithmetic
   – Event Selectors allow for regular expression matching of properties
   – Event Selectors may match on Domain and Range collections allowing criteria to be changed dynamically
   – Event Receivers may dynamically change selection criteria between receive operations
   – Event Selectors may be pre-validated for reuse, eliminating run-time syntax errors
   – Selection may be performed against Annotated Fields allowing data-aware filtering by payload content

More examples:

Selection Clause:

       ( PaymentIndicator IS NOT NULL ) 
  AND 
       ( TransferDate > datetime( '17.03.10 01:36' ) ) 
  AND
       PaymentFileName MATCHES '.*\\.xml'

Selection Clause:

       ( BranchIdentifier BETWEEN 0 AND  CaymanId_MAX ) 
  AND 
       ( AccountName  LIKE 'T_x%' ) 
  AND 
       StartDate  IN ( Domain.Valid_Dates )

Event selectors can indirectly reference payload of certain event types. DataEvents, DeltaEvents as well as other event datagrams that support Event Annotations may export payload values into previously defined user-defined properties, thereby allowing such elements to be used in selector expressions.

An event selector matches the event if the selector evaluates to true when the event's header field values and property values are substituted for their corresponding identifiers in the selector.

Selector allows to specify almost any conditions on event properties' values which should be satisfied for an event to be consumed. The following common symbols and keywords can be used in a selector expression:

    '(', ')', '=', '<', '>', '!=', '<>', '<=', '>=', 'true', 'false',
    'and', 'or', 'not', 'null', 'is null', 'is not null', 'between',
    'not between', '+', '-', '*', '/', 'in', 'not in', 'datetime',
    'like', 'not like', 'escape', '%', '_', 'matches', 'not matches'.

The syntax of all the conditions is very similar to Java if-statements except that keywords '=', 'and', 'or', 'not' are used instead of '==', '&&', '||', '!'. Here are the examples of equivalent expressions:

    x is null                                   ~   x = null
    x is not null                               ~   x != null
    x between 1 and 2                           ~   (x >= 1) and (x <= 2)
    x not between 1 and 2                       ~   (x < 1) or (x > 2)
    str in ('Value1', 'Value2', 'Value3')       ~   (str = 'Value1') or (str = 'Value2') or (str = 'Value3')
    str not in ('Value1', 'Value2', 'Value3')   ~   (str != 'Value1') and (str != 'Value2') and (str != 'Value3')

Keyword 'datetime' is used for comparing dates in different formats. For example to check if an event dateProperty is before than January the 1-st 2010 it is necessary to write the following expression:

    dateProperty < datetime('01.01.2010')

Keywords 'like', 'not like', 'escape', '%', '_' are used to check string properties (similar to SQL language). Keyword 'like' requires that the string property matches the following expression and 'not like' - that it doesn't match. Symbol '%' means any (including empty) set of characters and '_' means any single character. The escaping symbol can be specified via 'escape' keyword, for example: "escape '\'".

Keywords 'matches' and 'not matches' are also used to check string properties. The regular expressions after these keywords have the same syntax as regular expressions in Java .

Examples

Consider we have an event with the following properties:

   severity = 'Critical'
   source   = 'DB_Database.main'
   time     = '03/17/10 01:36:37.193'
   level    = 3
The following table shows the value of selector expressions for this event:

Expression Value
notExistentProperty false
notExistentProperty = 5 false
severity is null false
(level < 4) and (severity != null) true
(level between 2 and 4) or (severity = NULL) true
((level + 1) / 4 * 2) not between 2 and 4 false
not (severity in ('Critical', 'Warning') or (level > 4)) false
time > datetime('16.03.2010 01:36:37.193') true
source like 'DB\_Database_main' escape '\' true
source not like '%Database.%' false
source matches '.*_Database\.[a-z]+' true
source not matches '\w+Database\.main' false

Selector syntax

An event selector is a String whose syntax is based on a subset of the SQL92 conditional expression syntax. The event selector extends this capability by introducing a regular expression matching option and by allowing dispatchers to define Dynaimc Lookup tables that may be used in the extended IN (Table Name) syntax of the selector. If the value of a event selector is an empty string, the value is treated as a null and indicates that there is no selector for the event consumer.

The order of evaluation of an event selector is from left to right within precedence level. Parentheses can be used to change this order.

Predefined selector literals and operator names are shown here in uppercase; however, they are case insensitive.

A selector can contain:

Null Values

As noted above, property values may be NULL. The evaluation of selector expressions containing NULL values is defined by SQL92 NULL semantics. A brief description of these semantics is provided here.

SQL treats a NULL value as unknown. Comparison or arithmetic with an unknown value always yields an unknown value.

The IS NULL and IS NOT NULL operators convert an unknown value into the respective TRUE and FALSE values.

The boolean operators use three-valued logic as defined by the following tables:

The definition of the AND operator

| AND  |   T   |   F   |   U
+------+-------+-------+-------
|  T   |   T   |   F   |   U
|  F   |   F   |   F   |   F
|  U   |   U   |   F   |   U
+------+-------+-------+-------

The definition of the OR operator

| OR   |   T   |   F   |   U
+------+-------+-------+--------
|  T   |   T   |   T   |   T
|  F   |   T   |   F   |   U
|  U   |   T   |   U   |   U
+------+-------+-------+-------

The definition of the NOT operator

| NOT
+------+------
|  T   |   F
|  F   |   T
|  U   |   U
+------+-------

Defined in: </home/ubuntu/streamscape/NeeveBuild/stjsapi/src/main/webapp/js/Selector.js>.

Namespace Summary
Constructor Attributes Constructor Name and Description
 
Namespace Detail
Selector

Copyright © 2015-2021 StreamScape Technologies. All rights reserved.