Defining Event Listeners

An event listener observes each event from the input queue. When an event or a pattern of events matches the specified pattern, the event listener triggers and causes the engine to execute the corresponding operations.

You can use the addEventListener to define or dynamically add event listeners within a monitor.

Syntax

addEventListener(handler, [eventType], [condition], [times="all"], [at], [wait], [within], [exceedTime])

Arguments

handler is a callback function to be invoked when the event listener triggers.

  • If handler is triggered by each matched event (with eventType specified), it is a unary function that takes the matched event as its parameter.

  • If handler is triggered by a scheduled time interval (without eventType), it is a function without any parameters.

def action1(stockVal){
    // insert attributes of event stockVal to a shared table
    insert into objByName("sharedUSPrices") values([stockVal.price, stockVal.qty])
}

You can add listeners dynamically in a handler. For example:

def action1(stockVal){
    insert into objByName("sharedUSPrices") values([stockVal.price, stockVal.qty])
    // add a listener
    addEventListener(handler=action2, eventType="Stock", condition=<self.price > Stock.price>)
}

eventType (optional) is a string scalar indicating the event to be monitored. If set to "any", the handler will be triggered for any event that matches the specified condition.

condition (optional) is metacode of Boolean expression to identify the event or pattern of events that you want to match. For example, when eventType is "Stock", condition can be <Stock.price > 10 and Stock.qty < 10>.

times (optional) is "all" or an integer that specifies the lifetime of an event listener by setting a limit on the number of times the handlercan be triggered. The default value is "all", which means the listener remains active within the CEP engine, continuously monitoring for events and invoking the handler until the engine is explicitly dropped.

at (optional) is a tuple of length 6 that specifies the scheduled time for triggering the handler. The tuple takes the following form: (seconds, minutes, hours, days_of_the_week, days_of_the_month, months). For example, at = (0, 5, , , , ) means the handler will be triggered at the 5th minute of every hour.

wait (optional) is of DURATION type, indicating the interval to trigger the handler. For example, wait = 60s means handler is triggered every 60 seconds.

within (optional) is a DURATION scalar that specifies the time interval during which the handler is triggered by matched events. When within is specified, timesmust be set to 1. For example, when within=60s,

  • If one or more matching events occur within a 60-second interval, the handler is invoked for the first matching event and the event listener will be removed once the handler is triggered.

  • If no matching events occur within this interval, the event listener is automatically removed after 60s.

exceedTime (optional) is a DURATION scalar that specifies the time interval during which the handler is triggered by the absence of matched events. If exceedTime is specified, times must be set to 1. For example, exceedTime=60s,

  • If no matching events occur within a 60-second interval, the handler is invoked after 60s. The event listener will be removed once the handler is triggered.

  • If one or more matching events occur within this interval, the listener is automatically removed.

Note:

Event listeners can be triggered by:

  • specific events: eventType (required), condition;

  • time conditions: at or wait;

  • a combination of events and time: eventType (required), condition, combined with within or exceedTime.

When defining a listener, do not mix parameters for different trigger conditions. For example, you should not specify an eventType and a wait time together.

Examples

Listeners triggered by specific events

// listen for stocks with prices higher than 10.0
addEventListener(handler=action, eventType=`Stock, condition=<Stock.price > 10.0>)

// listen for the "Stock" event
addEventListener(handler=action, eventType=`Stock)

// listen for any event
addEventListener(handler=action, eventType="any")

Listeners triggered by time condition

// trigger at 8:30 every day
addEventListener(handler=action, at=(0,30,8,,,))

// trigger every 60s
addEventListener(handler=action, wait=60s)

// trigger once after 60s
addEventListener(handler=action, wait=60s,times=1)

Listeners triggered by events and time

// listen for stocks with prices higher than 10.0
// trigger if a stock with prices higher than 10.0 occurs within 60s 
addEventListener(handler=action, eventType=`Stock, condition=<Stock.price > 10.0>, within = 60s,times=1)

// trigger if a stock with prices higher than 10.0 does not occur within 60s
addEventListener(handler=action, eventType=`Stock, condition=<Stock.price > 10.0>, exceedTime= 60s,times=1)