Event primaries
The event primary is the simplest form of an event expression clause and can be combined with other event primaries and event operators to form more complex event expressions.
An event primary can be an event template (see
Event templates) optionally prefixed with
completed or
unmatched, or it can be a timer (see
Timers).
Event templates are constructs that allow you to specify filtering or matching criteria based on values of one or more of an event's fields.
The completed operator
A completed event template matches only after all other work is completed. When an event that matches a completed template comes into the correlator, the correlator:
1. Runs all of the event's normal or unmatched event listeners. Normal event templates do not specify the completed or unmatched keyword.
2. Processes all routed events that result from those event listeners.
3. Triggers the completed event listeners.
For example:
on all completed A(f < 10.0) {}
The unmatched operator
An unmatched event template matches against events for which both of the following are true:
Except for
completed and
unmatched event templates, the event is not a match with any other event template currently loaded in the context.
The event matches the
unmatched event template.
The correlator processes events as follows:
1. The correlator tests the event against all normal event templates in the context. Normal event templates do not specify the completed or unmatched keyword. If there are any matches, those event listeners trigger and the correlator executes those event listener actions. If execution of the event listener actions routes any events, the correlator then processes those events.
2. If the correlator does not find a match, the correlator tests the event against all event templates in the context that specify the unmatched keyword. If the correlator finds one or more matches, it triggers an event listener for each match found. In other words, if multiple unmatched event templates match a given event, they all trigger. The correlator executes the event listener actions defined by the event listeners that trigger. If any events are routed during execution of those actions, the correlator processes the routed events.
3. The correlators tests the event against all event templates in the context that specify the completed keyword. If the correlator finds one or more matches, it triggers an event listener for each match found.
Example
For example, suppose you have the following code:
on all A("foo", < 10) as a {
print "Match: " + a.toString();
a.count := a.count+1; // count is second field of A
route a;
}
on all unmatched A(*,*) as a {
print "Unmatched: " + a.toString();
}
on all completed A("foo", *) as a {
print "Completed: " + a.toString();
}
The incoming events are as follows:
A("foo", 8);
A("bar", 7);
The output is as follows.
Match: A("foo", 8)
Match: A("foo", 9)
Unmatched: A("foo", 10)
Completed: A("foo", 10)
Completed: A("foo", 9)
Completed: A("foo", 8)
Unmatched: A("bar", 7)
Specify the unmatched keyword with care. Be sure to communicate with any others who write event templates. If you are relying on an unmatched event template, and someone else injects a monitor that happens to match some events that you expected to match your unmatched event template, you will not get the results you expect. The firing of an event-specific unmatched listener is suppressed if an on any() listener matches the event (not just a type-specific listener).
Parenthesized event expressions
Just as with primary and bitwise expressions, event expressions can be enclosed in parentheses to control expression evaluation order or to improve readability.