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 = 3The 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:
- Literals:
- A string literal is enclosed in single quotes, with a single quote
represented by doubled single quote; for example,
'literal'
and'literal''s'
. Like string literals in the Java programming language, these use the Unicode character encoding. - An exact numeric literal is a numeric value without a decimal
point, such as
57
,-957
, and+62
; numbers in the range oflong
are supported. Exact numeric literals use the integer literal syntax of the Java programming language. - An approximate numeric literal is a numeric value in scientific
notation, such as
7E3
and-57.9E2
, or a numeric value with a decimal, such as7.
,-95.7
, and+6.2
; numbers in the range ofdouble
are supported. Approximate literals use the floating-point literal syntax of the Java programming language. - The boolean literals
TRUE
andFALSE
.
- A string literal is enclosed in single quotes, with a single quote
represented by doubled single quote; for example,
- Identifiers:
- An identifier is an unlimited-length sequence of letters
and digits, the first of which must be a letter. A letter is any
character for which the method
Character.isJavaLetter
returns true. This includes'_'
and'$'
. A letter or digit is any character for which the methodCharacter.isJavaLetterOrDigit
returns true. - Identifiers cannot be the names
NULL
,TRUE
, andFALSE
. - Identifiers cannot be
NOT
,AND
,OR
,BETWEEN
,LIKE
,IN
,IS
, orESCAPE
. - Identifiers are either header field references or property
references. The type of a property value in an event selector
corresponds to the type used to set the property. If a property
that does not exist in an event is referenced, its value is
NULL
. - The conversions that apply to the get methods for properties do not
apply when a property is used in an event selector expression.
For example, suppose you set a property as a string value, as in the
following:
myEvent.setStringProperty("NumberOfOrders", "2");
The following expression in an event selector would evaluate to false, because a string cannot be used in an arithmetic expression:"NumberOfOrders > 1"
- Identifiers are case-sensitive.
- Event header field references are restricted to
eventSource, eventId, durable, eventKey, eventGroupId, correlationId, saToken, eventReplyTo, eventForwardTo, timeStamp, eventExpiration, dataProtected, principal, credential, acl, coalesced
.
- An identifier is an unlimited-length sequence of letters
and digits, the first of which must be a letter. A letter is any
character for which the method
- White space is the same as that defined for the Java programming language: space, horizontal tab, form feed, and line terminator.
- Expressions:
- A selector is a conditional expression; a selector that evaluates
to
true
matches; a selector that evaluates tofalse
or unknown does not match. - Arithmetic expressions are composed of themselves, arithmetic operations, identifiers (whose value is treated as a numeric literal), and numeric literals.
- Conditional expressions are composed of themselves, comparison operations, and logical operations.
- A selector is a conditional expression; a selector that evaluates
to
- Standard bracketing
()
for ordering expression evaluation is supported. - Logical operators in precedence order:
NOT
,AND
,OR
- Comparison operators:
=
,>
,>=
,<
,<=
,<>
(not equal)- Only like type values can be compared. One exception is that it
is valid to compare exact numeric values and approximate numeric
values; the type conversion required is defined by the rules of
numeric promotion in the Java programming language. If the
comparison of non-like type values is attempted, the value of the
operation is false. If either of the type values evaluates to
NULL
, the value of the expression is unknown. - String and boolean comparison is restricted to
=
and<>
. Two strings are equal if and only if they contain the same sequence of characters.
- Only like type values can be compared. One exception is that it
is valid to compare exact numeric values and approximate numeric
values; the type conversion required is defined by the rules of
numeric promotion in the Java programming language. If the
comparison of non-like type values is attempted, the value of the
operation is false. If either of the type values evaluates to
- Arithmetic operators in precedence order:
+
,-
(unary)*
,/
(multiplication and division)+
,-
(addition and subtraction)- Arithmetic operations must use numeric promotion in the Java programming language.
arithmetic-expr1 [NOT] BETWEEN arithmetic-expr2 AND arithmetic-expr3
(comparison operator)"age BETWEEN 15 AND 19"
is equivalent to"age >= 15 AND age <= 19"
"age NOT BETWEEN 15 AND 19"
is equivalent to"age < 15 OR age > 19"
identifier [NOT] IN (string-literal1, string-literal2,...)
(comparison operator whereidentifier
has aString
orNULL
value)"Country IN (' UK', 'US', 'France')"
is true for'UK'
and false for'Peru'
; it is equivalent to the expression"(Country = ' UK') OR (Country = ' US') OR (Country = ' France')"
"Country NOT IN (' UK', 'US', 'France')"
is false for'UK'
and true for'Peru'
; it is equivalent to the expression"NOT ((Country = ' UK') OR (Country = ' US') OR (Country = ' France'))"
- If identifier of an
IN
orNOT IN
operation isNULL
, the value of the operation is unknown.
identifier [NOT] LIKE pattern-value [ESCAPE escape-character]
(comparison operator, whereidentifier
has aString
value;pattern-value
is a string literal where'_'
stands for any single character;'%'
stands for any sequence of characters, including the empty sequence; and all other characters stand for themselves. The optionalescape-character
is a single-character string literal whose character is used to escape the special meaning of the'_'
and'%'
inpattern-value
.)"phone LIKE '12%3'"
is true for'123'
or'12993'
and false for'1234'
"word LIKE 'l_se'"
is true for'lose'
and false for'loose'
"underscored LIKE '\_%' ESCAPE '\'"
is true for'_foo'
and false for'bar'
"phone NOT LIKE '12%3'"
is false for'123'
or'12993'
and true for'1234'
- If
identifier
of aLIKE
orNOT LIKE
operation isNULL
, the value of the operation is unknown.
identifier IS NULL
(comparison operator that tests for a null header field value or a missing property value)"prop_name IS NULL"
identifier IS NOT NULL
(comparison operator that tests for the existence of a non-null header field value or a property value)"prop_name IS NOT NULL"
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: <D:\Programs\Neeve\Projects\NeeveBuild16\stjsapi/src/main/webapp/js\Selector.js>.
Constructor Attributes | Constructor Name and Description |
---|---|