This Section provides a full reference for the metadata annotations used for Event Processing extensions to Prova. Each of the annotations below apply to either rcvMsg or rcvMult primitives.
@and(GID)
This annotation is attached to an exit reaction for a reaction group. The group ID GID is the logical name of the group. At the time the reaction primitive (rcvMsg or rcvMult) annotated with @and executes, all members of the group are assumed to have already executed. This means that the creation of the group must be done by sequentially initialising the group member reactions (event channels) and then visiting the exit reaction with precise designation of the logical connective associated with the group.
The @and annotation requires ALL the event channels to be successfully proved.
For positive channels, the channel is proved if a matching event is detected (subject to multiplicity constraints if it is annotated with @count).
For negative channels, the channel is proved if at the time the AND reaction group is terminated (for example, by an elapsed timeout), there has been no detection of a single reaction or for @count annotated channels, of the required number of reactions.
For control channels, detecting events on such channel does not directly affect the successful AND group detection but only influences it by stopping, pausing, or resuming other channels in the group.
In a special case when an AND event group consists only of control channels, the group can be terminated if all control channels are terminated individually or the group timeout expires, but no pattern is ever detected.
The following example of an AND group includes two conjuncted event channels: login and logout, which must arrive before the timeout of 2000 milliseconds specified on the exit channel is elapsed. The AND group sends an internal message with message type and to the engine itself, that is intercepted by the exit channel. The payload represented by the variable Events communicates the full trace of events that resulted in positive event pattern detection. Alternatively, if the timeout elapses and detection is unsuccessful with events for either of the conjuncted channels not yet detected, the group sends a different internal message with the message type timeout, intercepted by the timeout channel. The timeout channels are very useful for assisting with diagnosis as well as reacting to edge conditions, as it communicates the trace of all so far received events in the payload represented by the variable Events.
@count(MinCount[,MaxCount[,ignore|record|strict]])
This annotation used in AND groups specifies the range between MinCount and MaxCount as the required multiplicity for the matching events for this channel to be proved. The third argument talkes either of the three pre-defined values: ignore, record, or strict.
The ignore setting results in all events after MaxCount is reached to be completely ignored. Such subsequent events do not invalidate the positive detection status set after MinCount events are detected.
The record setting makes the events arriving after MaxCount to be recorded as part of the eventual detected pattern trace. Such subsequent events do not invalidate the positive detection status set after MinCount events are detected.
The strict setting results in the invalidation of the event channel and, obviously, of the containing AND pattern if one more event arrives after MaxCount events are already detected.
There are a few abbreviated forms of this annotation.
@count(0,0,record) is abbreviated as @count(-1)
This variant sets the multiplicity to *, in the regular expression sense, so that an indefinite number of matching events can be received and recorded as part of the eventual detected pattern trace.
@count(N,N,record) is abbreviated as @count(N,-1)
This variant sets the multiplicity to N+, in the regular expression sense, so that at least N matching events must be received for the event channel to be proved. All received events are recorded as part of the eventual detected pattern.
@count(N,N,ignore) is abbreviated as @count(N)
This variant sets the multiplicity to N+, in the regular expression sense, so that at least N matching events must be received for the event channel to be proved. All events received after the first N are completely ignored.
The following example is a fairly interesting event pattern. The variable Basket is pre-initialised with a Java Set collection. For two seconds, the pattern watches for additions and removals from a basket. An indefinite number of additions is allowed (and recorded in the pattern trace) while the set Basket accumulates all added ID's. At least one removal is expected, such that the Basket does not contain the same ID. Such removal along with all subsequent removals are recorded in the pattern trace.
@group(GID)
The annotation attached to inline reactions to mark them as event channels so that they form part of a reaction group. The GID parameter is the logical name of the group. Note that there can be many active instances of groups with the same name at any moment of time, with one group created each time the engine encounters a group with a distinct logical name in any given goal or reaction to a message (which is, of course, also a goal in Prova). The type of the group is specified on the exit channel using the group type @and or @or annotations. The main ideas behind using reaction groups for event processing are discussed in Event processing using reaction groups.
@id(ID)
This annotation is the foundation of the dynamic event channels mechanism built into Prova. It assigns a unique (within the containing reaction group) logical identifier ID to the annotated event channel. As the channel acquires this identifier, it can then be controlled from other control channels, with annotations such as @stop or @pause by explicitly targeting this ID. The following example hows how an update event stops (and completely removes) the first login channel.
@not
Inline reactions annotated with @not are called negative event channels. Essentially, it means that the channel can only be detected successfully if the matching event(s) are not detected. Exactly how many events is determined by the presence of other annotations affecting the required multiplicity of the events in the channel. The behavior is also different depending on whether this event channel belongs to an AND or an OR group.
@not for AND groups
Consider the following example in which it may happen that other event channels apart from the one annotated with not are successful when timeout of the containing reaction group expires. Should it happen, the group timeout actually results in a successful event pattern detection. Conversely, the group instance fails if a matching event in the logout channel is detected.
This behavior can be further affected by a @count annotation. If the count mode is strict, only the number of matching events within the range specified by the first two arguments of @count invalidates the group on timeout. If the mode is ignore or record, reaching the minimum number of events specified by @count immediately fails the AND group instance.
The example below shows how the strict mode sets the required multiplicity of the detected events in the remove channel to be anything but one.
@not for OR groups
In the case of OR groups, the @not also requires that the matching event(s) are not detected in specified multiplicities but upon timeout, this channel on its own may decide whether the overall group was successful.
In the example below, if the group timeout expires and neither login not logout have been detected, the group will be successful. It will, of course, detect the pattern should the matching login be detected before timeout and the logout channel alone will be terminated should a logout be detected before timeout and a login.
Remember that OR groups can only have @size but not @count annotations. The following example shows that the @size(N) annotation sets a limit of N on the detected events so that if two login events arrive before the group timeout (and, of course, before a logout event, which would have resulted in immediate pattern detection), the negative channel will be terminated on its own.
@optional
A reaction annotated with @optional is typically used in AND groups to specify an optional contribution to the overall event pattern. This follows the idea that event patterns should not be over-specified and allow for necessary variability. Any events on this channel are entirely optional. The annotated reaction will record the first matching event if detected during the lifetime of the containing group but will ignore all subsequent matches.
@or
This annotation is attached to an exit channel for a reaction group. The group ID GID is the logical name of the group. At the time the annotated reaction primitive (rcvMsg or rcvMult) executes, all members of the group are assumed to have already executed. This means that the creation of the group must be done by sequentially initialising the group member reactions (event channels) and then visiting the exit reaction with precise designation of the logical connective associated with the group.
The @or annotation requires EITHER of the event channels to be successfully proved.
For positive channels, the channel is proved if a matching event is detected (subject to multiplicity constraints if it is annotated with @size).
For negative channels, the channel is proved if at the time the OR reaction group is terminated (for example, by an elapsed timeout), there has been no detection of a single reaction or for @size annotated channels, of the required number of reactions.
For control channels, detecting events on such channel does not directly affect the successful OR group detection but only influences it by stopping, pausing, or resuming other channels in the group.
In a special case when an OR event group consists only of control channels, the group can be terminated if all control channels are terminated individually or the group timeout expires, but no pattern is ever detected.
The following example of an OR group detects within two seconds from the time the group instance is created either two logins from an IP2 different from pre-defined IP or one logout for the same IP. When the pattern is detected, the exit channel fires and the variable Events is bound to a trace of events detected in the pattern.
OR groups are the right type of groups that can be used with recurring pattern outputs using the recurring @size or recurring @timer annotations. These annotations are used for updating standard and custom aggregators and emitting the aggregations at regular event counts or time intervals.
@pause(ID[,ID])*
This annotation is part of the dynamic event channels functionality. It targets a list of controlled channels with the specified ID's and pauses them from the previous active state. In a paused state, the reaction is suspended, i.e., it is still part of the group (so, for example, an AND group will not succeed without that channel) but as far as the inbound events are concerned, neither of them will match the paused reaction.
This pause/resume example shows how @pause and resume work together.
@paused
This annotation is part of the dynamic event channels functionality. It makes the channel start in a paused state. The channel must also be given an identifier with an @id annotation for another control channel to be able to resume it.
In the following example, the login channel with identifier id1 starts in a paused state then if an update event is detected for the matching User and IP, the login channel is resumed via a @resume annotation that specifically targets the channel with identifier id1.
@resume(ID[,ID])*
This annotation is part of the dynamic event channels functionality. It targets a list of controlled channels with the specified ID's and resumes their active state from the previous paused state. In a paused state, the reaction is suspended, i.e., it is still part of the group (so, for example, an AND group will not succeed without that channel) but as far as the inbound events are concerned, neither of them will match the paused reaction.
In the following example, the query events pause the login channel but the update events resume it.
@size(Size)
This annotation used in OR groups sets the minimum number of events required for the annotated event channel to be proved and consequently, the OR group to be successfully detected. This example of an OR group shows the use of this annotation. In negative channels, i.e., channels annotated with @not, when the timeout on the OR group expires, the group could still detect a pattern, if the minimum number of events specified in the @size annotation is not reached.
@size(Size,RecurringSize,Aggregator)
This annotation is used in OR groups for repeated emission of pattern detections, typically for regularly outputting incremental aggregations over new events. The first output occurs when the event count reaches Size and subsequent emissions occur every RecurringSize event. The Aggregator is a Java object that can be a standard built-in or a custom aggregator capable of storing some useful information for each inbound event. In the example below, the standard MapCounter aggregator simply counts events for each key equal to I % 5 where I is part of the event payload a(I).
The recurring @timer annotation is similar but outputs events regularly at fixed time intervals.
@stop(ID[,ID])*
This annotation is part of the dynamic event channels functionality. It targets a list of controlled channels with specified ID's and stops them, completely removing them from memory. An event channel with such annotation is a control channel and as such does not directly participate in the event pattern detection, but indirectly affects the detection by controlling other channels. In the case of an AND group, the fact that an event channel is gone (stopped) is assumed to mean that there is no such conjunct hence the overall event pattern detection is then reduced to ensuring that all remaining event channels are successfully proved.
In the next example, the logout is a control channel that, when detected, stops the, otherwise indefinitely active, purchase channel, and consequently, results in the termination of the containing AND group and event pattern detection.
@timeout(Timeout)
This annotation works for individual inline reactions, grouped event channels, and exit channels. When an inline reaction annotated with @timeout is created, a time limit Timeout (represented as a time period) is imposed on its lifetime, so that when the timeout expires, the inline reaction or event channel are removed completely. In the case of an event channel, the latter then does not contribute a positive detection to the containing group. In a case of an exit channel, the group instance itself has a timeout, so that that particular group instance is completely removed when the timeout expires. In this case, a special internal message is sent to the timeout channel, containing the trace of all events recorded so far in its payload.
The following example demonstrates pretty much all of the above cases. The logout event channel times out in one second on its own but the group also has a timeout of two seconds. The timeout channel receives the event traces that resulted from timed out group instances.
@timer(Delay)
Consider the following use case: we need to repeat a certain action (typically sending out a message) at regular time intervals represented by the value of Delay (represented as a time period) and we want to terminate our retries after a given timeout. If a positive response is detected within this timeout, the retries will have to stop and a follow-up action will proceed. If the timeout is reached with all retries failing, the timeout exit channel will have a chance to execute a corrective action. The following reaction group satisfies all these requirements.
The first reaction is a control channel (annotated with @stop) that detects an expected response from the acquired service, terminates the reaction group and follows up with other actions. The second reaction with the @timer annotation does not in fact react to any concrete message pattern but results in the positive exit channel for the group to be executed. The third reaction is an exit channel that is executed every 500 ms and does not terminate the reaction group but rather, retries a request to acquire the service. The last reaction is a timeout exit channel that is executed only if all retries do not result in a positive response and so further corrective actions may follow.
@timer(Delay,RecurringDelay,Processor)
This annotation is used in OR groups for repeated emission of pattern detections, typically for regularly outputting incremental aggregations or accumulations over new events. The first output occurs when the first timer elapses after the amount of time equal to Delay (represented as a time period) and subsequent emissions occur after each subsequent time interval equal to RecurringDelay (represented as a time period). The Processor is a Java object that is typically a standard built-in or a custom aggregator or accumulator capable of storing some useful information for each inbound event. In the example below, the standard MapCounter aggregator simply counts events for each key equal to I % 5. The counter is reset every 25 milliseconds.
The second example shows how easy it is to modify the aggregation logic executed in the reaction guard to emit instead a histogram for the values in a particular field of the payload.
@vars
This annotation (only applicable in AND groups) "outjects" the local variables by name into the context of the running group instance. It also instructs the group instance to record all matching events for the annotated event channel. On top of that, when other event channels outject their variables, it matches the payloads for these channels according to (1) the matching of values of all variables with the same name and (2) the matching of any remaining variables according to constraints specified in optional @where annotations.
To understand why this construct is needed, consider this example of using reaction guards in a typical "followed by" event pattern.
Once the first event arrives, it binds the variables User and IP to concrete values by matching them against the logout event payload. The second event channel for login events then uses a guard IP2!=IP by comparing the already bound values of IP and IP2.
In the case of an inherently unordered AND group, it is not known in which order the conjuncted events will arrive so it is impossible to use guards on variables that will be potentially only known in future.
The following example based on the @vars annotation detects within 1.5 seconds up to four pairs of unordered login/logout pairs with matching values for User and IP variables.
This is a typical output from this pattern:
@where(WhereExpression)
This annotation (working only in AND groups) complements the @vars annotation by executing a simple embedded expression language for the variables outjected by the event channels in the group. If the expression evaluates to true for the variables, the participating events form a tuple that is a successful event pattern detection. Note that they may be more than one tuple emitted triggered by the arrival of an event on any participating event channel.
The following gives the full ANTLR3 grammar for the @where expression language.
A commented example of using the @where annotation follows.
Time periods
If a time period is an integer number, it is assumed to be a value in milliseconds. If it is a string, it is parsed as: