The createPattern method on the EPAdministrator administrative interface creates pattern statements for the given pattern expression string.

This is an example pattern expression that matches on every ServiceMeasurement events in which the value of the latency event property is over 20 seconds, and on everyServiceMeasurement events in which the success property is false. Either one or the other condition must be true for this pattern to matches.

every ( spike=ServiceMeasurement(latency>20000) or error=ServiceMeasurement(success=false) )

The Java code to create this trigger is below.

EPAdministrator admin = EPServiceProviderManager.getDefaultProvider().getEPAdministrator();

String eventName = ServiceMeasurement.class.getName();

EPStatement myTrigger = admin.createPattern(
    "every ( spike=" + eventName + "(latency>20000) or error=" + eventName + "(success=false) )");

The pattern expression starts with an every operator to indicate that the pattern should fire for every matching events and not just the first matching event. Within the every operator in round brackets is a nested pattern expression using the or operator. The left hand of the or operator is a filter expression that filters for events with a high latency value. The right hand of the operator contains a filter expression that filters for events with error status. Filter expressions are explained in Section 5.3, “Filter Expressions”.

When a pattern fires it publishes one or more events to any listeners to the pattern statement. The listener interface is the net.esper.client.UpdateListener interface.

The example below shows an anonymous implementation of the net.esper.client.UpdateListener interface. We add the anonymous listener implementation to the myPattern statement created earlier. The listener code simply extracts the underlying event class.

myPattern.addListener(new UpdateListener()
{
	public void update(EventBean[] newEvents, EventBean[] oldEvents)
	{
		ServiceMeasurement spike = (ServiceMeasurement) newEvents[0].get("spike");
		ServiceMeasurement error = (ServiceMeasurement) newEvents[0].get("error");
		... // either spike or error can be null, depending on which occured
		... // add more logic here
	}
});

Listeners receive an array of EventBean instances in the newEvents parameter. There is one EventBean instance passed to the listener for each combination of events that matches the pattern expression. At least one EventBean instance is always passed to the listener.

The properties of each EventBean instance contain the underlying events that caused the pattern to fire, if events have been named in the filter expression via the name=eventType syntax. The property name is thus the name supplied in the pattern expression, while the property type is the type of the underlying class, in this example ServiceMeasurement.

Data can also be pulled from pattern statements via the iterator() method. If the pattern had fired at least once, then the iterator returns the last event for which it fired. The hasNext() method can be used to determine if the pattern had fired.

if (myPattern.iterator().hasNext())
{
	ServiceMeasurement event = (ServiceMeasurement) view.iterator().next().get("alert");
    ... // some more code here to process the event
}
else
{
    ... // no matching events at this time
}

The every operator indicates that the pattern expression should restart when the pattern matches. Without the every operator the pattern expressions matcher stops when the pattern matches once.

Thus the every operator works like a factory for the pattern expression contained within. When the pattern expression within it fires and thus quits checking for events, the every causes the start of a new pattern matcher listening for more occurances of the same event or set of events.

Every time a pattern expression within an every operator turns true a new active pattern matcher is started looking for more event(s) or timing conditions that match the pattern expression. If the every operator is not specified for an expression, the expression stops after the first match was found.

This pattern fires when encountering event A and then stops looking.

A

This pattern keeps firing when encountering event A, and doesn't stop looking.

every A

Lets consider an example event sequence as follows.

A₁ B₁ C₁ B₂ A₂ D₁ A₃ B₃ E₁ A₄ F₁ B₄

every ( A -> B )

every A -> B

A -> every B

every A -> every B

The examples show that it is possible that a pattern fires for multiple combinations of events that match a pattern expression. Each combination is posted as an EventBean instance to the update method in the UpdateListener implementation.

Similar to the Java && operator the and operator requires both nested pattern expressions to turn true before the whole expression turns true (a join pattern).

Pattern matches when both event A and event B are found.

A and B

Pattern matches on any sequence A followed by B and C followed by D, or C followed by D and A followed by B

(A -> B) and (C -> D)

Similar to the Java “||” operator the or operator requires either one of the expressions to turn true before the whole expression turns true.

Look for either event A or event B. As always, A and B can itself be nested expressions as well.

A or B

Detect all stock ticks that are either above or below a threshold.

every (StockTick(symbol='IBM', price < 100) or StockTick(symbol='IBM', price > 105)

The not operator negates the truth value of an expression. Pattern expressions prefixed with not are automatically defaulted to true.

This pattern matches only when an event A is encountered followed by event B but only if no event C was encountered before event B.

( A -> B ) and not C

The followed by -> operator specifies that first the left hand expression must turn true and only then is the right hand expression evaluated for matching events.

Look for event A and if encountered, look for event B. As always, A and B can itself be nested event pattern expressions.

A -> B

Pattern to match when 2 status events indicating an error occur.

StatusEvent(status='ERROR') -> StatusEvent(status='ERROR')

The timer:within guard acts like a stopwatch. If the associated pattern expression does not turn true within the specified time period it is stopped and permanently false.

Pattern for all A events that arrive within 5 seconds.

every A where timer:within (5000)

Pattern for any A or B events in the next 5 seconds.

( A or B ) where timer:within (5000)

Pattern if for any 2 errors that happen 10 seconds within each other.

every (StatusEvent(status='ERROR') -> StatusEvent(status='ERROR') where timer:within (10000))

The timer:interval observer takes a wait time in milliseconds and waits for the defined time before the truth value of the observer turns true.

After event A arrived wait 10 seconds then indicate that the pattern matches.

A -> timer:interval(10000) 

An expression that matches every 20 seconds.

every timer:interval(20000)

The timer:at observer is similar in function to the Unix “crontab” command. At a specified time the expression turns true. The at operator can also be made to pattern match at regular intervals by using an every operator in front of the timer:at operator.

The syntax is: timer:at (minutes, hours, days of month, months, days of week [, seconds]).

The value for seconds is optional. Each element allows wildcard * values. Ranges can be specified by means of lower bounds then a colon ‘:’ then the upper bound. The division operator */x can be used to specify that every xth value is valid. Combinations of these operators can be used by placing these into square brackets([]).

This expression pattern matches every 5 minutes past the hour.

every timer:at(5, *, *, *, *)

The below at operator pattern matches every 15 minutes from 8am to 5pm on even numbered days of the month as well as on the first day of the month.

timer:at (*/15, 8:17, [*/2, 1], *, *)