7.6. Temporal Operations

7.6.1. Temporal Reasoning

Complex Event Processing requires the rules engine to engage in temporal reasoning. Events have strong temporal constraints so it is vital the rules engine can determine and interpret an event's temporal attributes, both as they relate to other events and the 'flow of time' as it appears to the rules engine. This makes it possible for rules to take time into account; for instance, a rule could state, "Calculate the average price of a stock over the last 60 minutes."

Note

JBoss BRMS Complex Event Processing implements interval-based time events, which have a duration attribute that is used to indicate how long an event is of interest. Point-in-time events are also supported and treated as interval-based events with a duration of 0 (zero).

7.6.2. Temporal Operations

JBoss BRMS Complex Event Processing implements the following temporal operators and their logical complements (negation):
  • After
  • Before
  • Coincides
  • During
  • Finishes
  • Finishes By
  • Includes
  • Meets
  • Met By
  • Overlaps
  • Overlapped By
  • Starts
  • Started By

7.6.3. After

The after operator correlates two events and matches when the temporal distance (the time between the two events) from the current event to the event being correlated falls into the distance range declared for the operator.
For example: 
$eventA : EventA( this after[ 3m30s, 4m ] $eventB )
This pattern only matches if the temporal distance between the time when $eventB finished and the time when $eventA started is between the lower limit of three minutes and thirty seconds and the upper limit of four minutes.
This can also be represented as follows: 
 3m30s <= $eventA.startTimestamp - $eventB.endTimeStamp <= 4m
The after operator accepts one or two optional parameters:
  • If two values are defined, the interval starts on the first value (3 minutes and 30 seconds in the example) and ends on the second value (4 minutes in the example).
  • If only one value is defined, the interval starts on the provided value and runs indefinitely with no end time.
  • If no value is defined, the interval starts at one millisecond and runs indefinitely with no end time.
The after operator also accepts negative temporal distances.
For example: 
$eventA : EventA( this after[ -3m30s, -2m ] $eventB )
If the first value is greater than the second value, the engine will automatically reverse them.
The following two patterns are equivalent to each other: 
$eventA : EventA( this after[ -3m30s, -2m ] $eventB ) 
   $eventA : EventA( this after[ -2m, -3m30s ] $eventB )

7.6.4. Before

The before operator correlates two events and matches when the temporal distance (time between the two events) from the event being correlated to the current event falls within the distance range declared for the operator.
For example: 
$eventA : EventA( this before[ 3m30s, 4m ] $eventB )
This pattern only matches if the temporal distance between the time when $eventA finished and the time when $eventB started is between the lower limit of three minutes and thirty seconds and the upper limit of four minutes.
This can also be represented as follows: 
 3m30s <= $eventB.startTimestamp - $eventA.endTimeStamp <= 4m
The before operator accepts one or two optional parameters:
  • If two values are defined, the interval starts on the first value (3 minutes and 30 seconds in the example) and ends on the second value (4 minutes in the example).
  • If only one value is defined, the interval starts on the provided value and runs indefinitely with no end time.
  • If no value is defined, the interval starts at one millisecond and runs indefinitely with no end time.
The before operator also accepts negative temporal distances.
For example: 
$eventA : EventA( this before[ -3m30s, -2m ] $eventB )
If the first value is greater than the second value, the engine will automatically reverse them.
The following two patterns are equivalent to each other: 
$eventA : EventA( this before[ -3m30s, -2m ] $eventB ) 
   $eventA : EventA( this before[ -2m, -3m30s ] $eventB )

7.6.5. Coincides

The coincides operator correlates two events and matches when both events happen at the same time.
For example: 
$eventA : EventA( this coincides $eventB )
This pattern only matches if both the start timestamps of $eventA and $eventB are identical and the end timestamps of both $eventA and $eventB are also identical.
The coincides operator accepts optional thresholds for the distance between the events' start times and the events' end times, so the events do not have to start at exactly the same time or end at exactly the same time, but they need to be within the provided thresholds.
The following rules apply when defining thresholds for the coincides operator:
  • If only one parameter is given, it is used to set the threshold for both the start and end times of both events.
  • If two parameters are given, the first is used as a threshold for the start time and the second one is used as a threshold for the end time.
For example: 
$eventA : EventA( this coincides[15s, 10s] $eventB )
This pattern will only match if the following conditions are met: 
abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 15s && 
   abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 10s

Warning

The coincides operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance internals.

7.6.6. During

The during operator correlates two events and matches when the current event happens during the event being correlated.
For example: 
$eventA : EventA( this during $eventB )
This pattern only matches if $eventA starts after $eventB and ends before $eventB ends.
This can also be represented as follows: 
$eventB.startTimestamp < $eventA.startTimestamp <= $eventA.endTimestamp < $eventB.endTimestamp
The during operator accepts one, two, or four optional parameters:
The following rules apply when providing parameters for the during operator:
  • If one value is defined, this value will represent the maximum distance between the start times of the two events and the maximum distance between the end times of the two events.
  • If two values are defined, these values represent a threshold that the current event's start time and end time must occur between in relation to the correlated event's start and end times.
    If the values 5s and 10s are provided, the current event must start between 5 and 10 seconds after the correlated event, and similarly the current event must end between 5 and 10 seconds before the correlated event.
  • If four values are defined, the first and second values will be used as the minimum and maximum distances between the starting times of the events, and the third and fourth values will be used as the minimum and maximum distances between the end times of the two events.

7.6.7. Finishes

The finishes operator correlates two events and matches when the current event's start timestamp post-dates the correlated event's start timestamp and both events end simultaneously.
For example: 
$eventA : EventA( this finishes $eventB )
This pattern only matches if $eventA starts after $eventB starts and ends at the same time as $eventB ends.
This can be represented as follows: 
$eventB.startTimestamp < $eventA.startTimestamp && 
   $eventA.endTimestamp == $eventB.endTimestamp
The finishes operator accepts one optional parameter. If defined, the optional parameter sets the maximum time allowed between the end times of the two events.
For example: 
$eventA : EventA( this finishes[ 5s ] $eventB )
This pattern matches if these conditions are met: 
$eventB.startTimestamp < $eventA.startTimestamp && 
   abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 5s

Warning

The finishes operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.

7.6.8. Finishes By

The finishedby operator correlates two events and matches when the current event's start time predates the correlated event's start time but both events end simultaneously. finishedby is the symmetrical opposite of the finishes operator.
For example: 
$eventA : EventA( this finishedby $eventB )
This pattern only matches if $eventA starts before $eventB starts and ends at the same time as $eventB ends.
This can be represented as follows: 
$eventA.startTimestamp < $eventB.startTimestamp && 
   $eventA.endTimestamp == $eventB.endTimestamp
The finishedby operator accepts one optional parameter. If defined, the optional parameter sets the maximum time allowed between the end times of the two events. 
$eventA : EventA( this finishedby[ 5s ] $eventB )
This pattern matches if these conditions are met: 
$eventA.startTimestamp < $eventB.startTimestamp && 
   abs( $eventA.endTimestamp - $eventB.endTimestamp ) <= 5s

Warning

The finishedby operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.

7.6.9. Includes

The includes operator examines two events and matches when the event being correlated happens during the current event. It is the symmetrical opposite of the during operator.
For example: 
$eventA : EventA( this includes $eventB )
This pattern only matches if $eventB starts after $eventA and ends before $eventA ends.
This can be represented as follows: 
$eventA.startTimestamp < $eventB.startTimestamp <= $eventB.endTimestamp < $eventA.endTimestamp
The includes operator accepts 1, 2 or 4 optional parameters:
  • If one value is defined, this value will represent the maximum distance between the start times of the two events and the maximum distance between the end times of the two events.
  • If two values are defined, these values represent a threshold that the current event's start time and end time must occur between in relation to the correlated event's start and end times.
    If the values 5s and 10s are provided, the current event must start between 5 and 10 seconds after the correlated event, and similarly the current event must end between 5 and 10 seconds before the correlated event.
  • If four values are defined, the first and second values will be used as the minimum and maximum distances between the starting times of the events, and the third and fourth values will be used as the minimum and maximum distances between the end times of the two events.

7.6.10. Meets

The meets operator correlates two events and matches when the current event ends at the same time as the correlated event starts.
For example: 
$eventA : EventA( this meets $eventB )
This pattern matches if $eventA ends at the same time as $eventB starts.
This can be represented as follows: 
abs( $eventB.startTimestamp - $eventA.endTimestamp ) == 0
The meets operator accepts one optional parameter. If defined, it determines the maximum time allowed between the end time of the current event and the start time of the correlated event.
For example: 
$eventA : EventA( this meets[ 5s ] $eventB )
This pattern matches if these conditions are met: 
abs( $eventB.startTimestamp - $eventA.endTimestamp) <= 5s

Warning

The meets operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.

7.6.11. Met By

The metby operator correlates two events and matches when the current event starts at the same time as the correlated event ends.
For example: 
$eventA : EventA( this metby $eventB )
This pattern matches if $eventA starts at the same time as $eventB ends.
This can be represented as follows: 
abs( $eventA.startTimestamp - $eventB.endTimestamp ) == 0
The metby operator accepts one optional parameter. If defined, it sets the maximum distance between the end time of the correlated event and the start time of the current event.
For example: 
$eventA : EventA( this metby[ 5s ] $eventB )
This pattern matches if these conditions are met: 
abs( $eventA.startTimestamp - $eventB.endTimestamp) <= 5s

Warning

The metby operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.

7.6.12. Overlaps

The overlaps operator correlates two events and matches when the current event starts before the correlated event starts and ends after the correlated event starts, but it ends before the correlated event ends.
For example: 
$eventA : EventA( this overlaps $eventB )
This pattern matches if these conditions are met: 
$eventA.startTimestamp < $eventB.startTimestamp < $eventA.endTimestamp < $eventB.endTimestamp
The overlaps operator accepts one or two optional parameters:
  • If one parameter is defined, it will define the maximum distance between the start time of the correlated event and the end time of the current event.
  • If two values are defined, the first value will be the minimum distance, and the second value will be the maximum distance between the start time of the correlated event and the end time of the current event.

7.6.13. Overlapped By

The overlappedby operator correlates two events and matches when the correlated event starts before the current event, and the correlated event ends after the current event starts but before the current event ends.
For example: 
$eventA : EventA( this overlappedby $eventB )
This pattern matches if these conditions are met: 
$eventB.startTimestamp < $eventA.startTimestamp < $eventB.endTimestamp < $eventA.endTimestamp
The overlappedby operator accepts one or two optional parameters:
  • If one parameter is defined, it sets the maximum distance between the start time of the correlated event and the end time of the current event.
  • If two values are defined, the first value will be the minimum distance, and the second value will be the maximum distance between the start time of the correlated event and the end time of the current event.

7.6.14. Starts

The starts operator correlates two events and matches when they start at the same time, but the current event ends before the correlated event ends.
For example: 
$eventA : EventA( this starts $eventB )
This pattern matches if $eventA and $eventB start at the same time, and $eventA ends before $eventB ends.
This can be represented as follows: 
$eventA.startTimestamp == $eventB.startTimestamp && 
   $eventA.endTimestamp < $eventB.endTimestamp
The starts operator accepts one optional parameter. If defined, it determines the maximum distance between the start times of events in order for the operator to still match: 
$eventA : EventA( this starts[ 5s ] $eventB )
This pattern matches if these conditions are met: 
abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 5s && 
   $eventA.endTimestamp < $eventB.endTimestamp

Warning

The starts operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.

7.6.15. Started By

The startedby operator correlates two events. It matches when both events start at the same time and the correlating event ends before the current event.
For example: 
$eventA : EventA( this startedby $eventB )
This pattern matches if $eventA and $eventB start at the same time, and $eventB ends before $eventA ends.
This can be represented as follows: 
$eventA.startTimestamp == $eventB.startTimestamp && 
   $eventA.endTimestamp > $eventB.endTimestamp
The startedby operator accepts one optional parameter. If defined, it sets the maximum distance between the start time of the two events in order for the operator to still match: 
$eventA : EventA( this starts[ 5s ] $eventB )
This pattern matches if these conditions are met: 
abs( $eventA.startTimestamp - $eventB.startTimestamp ) <= 5s && 
   $eventA.endTimestamp > $eventB.endTimestamp

Warning

The startsby operator does not accept negative intervals, and the rules engine will throw an exception if an attempt is made to use negative distance intervals.