Create event pattern expression and EPL statements via the administrative interface EPAdministrator.

This code snippet gets an Esper engine then creates an event pattern and an EPL statement.

EPServiceProvider epService = EPServiceProviderManager.GetDefaultProvider();
EPAdministrator admin = epService.EPAdministrator;

EPStatement 10secRecurTrigger = admin.CreatePattern(
  "every timer:at(*, *, *, *, *, */10)");

EPStatement countStmt = admin.CreateEPL(
  "select count(*) from MarketDataBean.win:time(60 sec)");

Note that event pattern expressions can also occur within EPL statements. This is outlined in more detail in Section 4.4.2, “Pattern-based Event Streams”.

The Create methods on EPAdministrator are overloaded and allow an optional statement name to be passed to the engine. A statement name can be useful for retrieving a statement by name from the engine at a later time. The engine assigns a statement name if no statement name is supplied on statement creation.

The createPattern and CreateEPL methods return EPStatement instances. Statements are automatically started and active when created. A statement can also be stopped and started again via the Stop and Start methods shown in the code snippet below.

countStmt.Stop();
countStmt.Start();

The Create methods on EPAdministrator also accept a user object. The user object is associated with a statement at time of statement creation and is a single, unnamed field that is stored with every statement. Applications may put arbitrary objects in this field. Use the UserObject property on EPStatement to obtain the user object of a statement.

Your application may create new statements or stop and destroy existing statements using any thread and also within event handlers or subscriber code. If using native object events, your application may not create or manage statements in the event object itself while the same event is currently being processed by a statement.

Esper provides three choices for your application to receive statement results. Your application can use all mechanisms alone or in any combination for each statement. The choices are:

Your application may attach one or more event handlers, zero or one single subscriber and in addition use the Pull API on the same statement. There are no limitations to the use of enumerator, subscriber or event handler alone or in combination to receive statement results.

The best delivery performance can generally be achieved by attaching a subscriber and by not attaching event handlers. The engine is aware of the event handlers and subscriber attached to a statement. The engine uses this information internally to reduce statement overhead. For example, if your statement does not have event handlers or a subscriber attached, the engine does not need to continuously generate results for delivery.

If your application attaches both a subscriber and one or more event handlers then the subscriber receives the result first before any of the event handlers.

If your application attaches more then one event handler then the event handlers receive results first in the order they were added to the statement, and To change the order of delivery among event handlers your application can add and remove event handlers at runtime.

If you have configured outbound threading, it means a thread from the outbound thread pool delivers results to the subscriber and event handlers instead of the processing or event-sending thread.

If outbound threading is turned on, we recommend turning off the engine setting preserving the order of events delivered to event handlers as described in Section 13.4.9.1, “Preserving the order of events delivered to listeners”. If outbound threading is turned on statement execution is not blocked for the configured time in the case a subscriber or listener takes too much time.

A subscriber object is a direct binding of query results to a CLR object. The object receives statement results via method invocation. The subscriber class does not need to implement an interface or extend a superclass. Only one subscriber object may be set for a statement.

Subscriber objects have several advantages over event handlers. First, they offer a substantial performance benefit: Query results are delivered directly to your method(s) through method calls, and there is no intermediate representation (EventBean). Second, as subscribers receive strongly-typed parameters, the subscriber code tends to be simpler.

This chapter describes the requirements towards the methods provided by your subscriber class.

The engine can deliver results to your subscriber in two ways:

select orderId, price, count(*) from OrderEvent

public class MySubscriber {
  ...
  public void Update(String orderId, double price, long count) {...}
  ...
}

select *, count(*) from OrderEvent

public void Update(OrderEvent orderEvent, long count) {...}

select *, count(*) from OrderEvent order, OrderHistory hist

public void Update(OrderEvent orderEvent, OrderHistory orderHistory, long count) {...}

select hist.*, order from OrderEvent order, OrderHistory hist

public void Update(OrderHistory orderHistory, OrderEvent orderEvent) {...}

public void Update(IDictionary<string, object> row) {...}

public void Update(Object[] row) {...}

select orderId, count(*) from OrderEvent.win:time(20 sec) group by orderId

public void Update(String, long count) {...}
public void UpdateRStream(String orderId, long count) {...}

// Called by the engine before delivering events to update methods
public void UpdateStart(int insertStreamLength, int removeStreamLength)

// To deliver insert stream events
public void Update(String orderId, long count) {...}

// To deliver remove stream events
public void UpdateRStream(String orderId, long count) {...}

// Called by the engine after delivering events
public void UpdateEnd() {...}

select * from OrderEvent.win:time(30 sec)

public void Update(OrderEvent[] insertStream, OrderEvent[] removeStream) {...}

Your application can subscribe to updates posted by a statement via the Events event on EPStatement. Your application must to provide an implementation of the UpdateEventHandler to the statement:

public void HandleEvents(Object sender, UpdateEventArgs updateEventArgs) { ... }
countStmt.Events += HandleEvents;

The following adds and event handler using an embedded lambda expression.

countStmt.Events += (sender, updateEventArgs) => MyMethod(updateEventArgs);

EPL statements and event patterns publish old data and new data to registered UpdateEventHandlers. New data published by statements is the events representing the new values of derived data held by the statement. Old data published by statements constists of the events representing the prior values of derived data held by the statement.

It is important to understand that UpdateEventHandlers receive multiple result rows in one invocation by the engine: the new data and old data parameters to your event handler are array parameters. For example, if your application uses one of the batch data windows, or your application creates a pattern that matches multiple times when a single event arrives, then the engine indicates such multiple result rows in one invocation and your new data array carries two or more rows.

The UpdateEventArgs object that is passed as part of the event handler is especially useful when the same event handler is registered with multiple statements, as the event argumetns contain the statement and engine instance in addition to the new and old data when the engine indicates new results to a event handler.

Subscribing to events posted by a statement is following a push model. The engine pushes data to event handlers when events are received that cause data to change or patterns to match. Alternatively, you need to know that statements serve up data that your application can obtain via the GetSafeEnumerator and GetEnumerator methods on EPStatement. This is called the pull API and can come in handy if your application is not interested in all new updates, and only needs to perform a frequent or infrequent poll for the latest data.

The GetSafeEnumerator method on EPStatement returns a concurrency-safe enumerator returning current statement results, even while concurrent threads may send events into the engine for processing. The safe enumerator guarantees correct results even as events are being processed by other threads. The cost is that the enumerator obtains and holds a statement lock that must be released via the Dispose method on the GetSafeEnumerator instance.

The GetEnumerator method on EPStatement returns a concurrency-unsafe enumerator. This enumerator is only useful for applications that are single-threaded, or applications that themselves perform coordination between the iterating thread and the threads that send events into the engine for processing. The advantage to this enumerator is that it does not hold a lock.

The next code snippet shows a short example of use of safe iterators:

EPStatement statement = epAdmin.CreateEPL("select avg(price) as avgPrice from MyTick");
// .. send events into the engine
// then use the pull API...
IEnumerator<EventBean> safeEnum = statement.GetSafeEnumerator();
while(safeEnum.MoveNext()) {
 // .. process event ..
 EventBean @event = safeEnum.Current;
 Console.WriteLine("avg:" + @event.Get("avgPrice");
}

This is a short example of use of the regular iterator that is not safe for concurrent event processing:

double averagePrice = (double) eplStatement.FirstOrDefault().Get("average");

The GetSafeEnumerator and GetEnumerator methods can be used to pull results out of all statements, including statements that join streams, contain aggregation functions, pattern statements, and statements that contain a where clause, group by clause, having clause or order by clause.

For statements without an order by clause, the GetEnumerator method returns events in the order maintained by the data window. For statements that contain an order by clause, the GetEnumerator method returns events in the order indicated by the order by clause.

Consider using the on-select clause and a named window if your application requires iterating over a partial result set or requires indexed access for fast iteration; Note that on-select requires that you sent a trigger event, which may contain the key values for indexed access.

Esper places the following restrictions on the pull API and usage of the GetSafeEnumerator and GetEnumerator methods:

The EPAdministrator interface provides the facilities for managing statements:

Certain configuration changes are available to perform on an engine instance while in operation. Such configuration operations are available via the GetConfiguration method on EPAdministrator, which returns a ConfigurationOperations object.

Please consult the SDK documentation of ConfigurationOperations for further information. The section Section 13.6, “Runtime Configuration” provides a summary of available configurations.

In summary, the configuration operations available on a running engine instance are as follows:

The EventSender interface processes event objects that are of a known type. This facility can reduce the overhead of event object reflection and type lookup as an event sender is always associated to a single concrete event type.

Use the method GetEventSender(String eventTypeName) to obtain an event sender for processing events of the named type:

EventSender sender = epService.EPRuntime.GetEventSender("MyEvent");
sender.SendEvent(myEvent);

For events backed by a CLR type, the event sender ensures that the event object equals the underlying class, or implements or extends the underlying class for the given event type name.

For events backed by a System.Collections.Generic.IDictionary (Map events), the event sender does not perform any checking other then checking that the event object implements Map.

For events backed by a System.Xml.XmlNode (XML DOM events), the event sender checks that the root element name equals the root element name for the event type.

A second method to obtain an event sender is the method GetEventSender(Uri[]), which takes an array of URIs. This method is for use with plug-in event representations. The event sender returned by this method processes event objects that are of one of the types of one or more plug-in event representations. Please consult Section 15.8, “Event Type And Event Object” for more information.

Your application can register an implementation of the UnmatchedListener interface with the EPRuntime runtime via the SetUnmatchedListener method to receive events that were not matched by any statement.

Events that can be unmatched are all events that your application sends into the runtime via one of the SendEvent or Route methods, or that have been generated via an insert into clause.

For an event to become unmatched by any statement, the event must not match any statement's event stream filter criteria. Note that the EPL where clause or having clause are not considered part of the filter criteria for a stream, as explained by example below.

In the next statement all MyEvent events match the statement's event stream filter criteria, regardless of the value of the 'quantity' property. As long as the below statement remains started, the engine would not deliver MyEvent events to your registered UnmatchedListener instance:

select * from MyEvent where quantity > 5

In the following statement a MyEvent event with a 'quantity' property value of 5 or less does not match this statement's event stream filter criteria. The engine delivers such an event to the registered UnmatchedListener instance provided no other statement matches on the event:

select * from MyEvent(quantity > 5)

For patterns, if no pattern sub-expression is active for an event type, an event of that type also counts as unmatched in regards to the pattern statement.

As your application may not require streaming results and may not know each query in advance, the on-demand query facility provides for ad-hoc execution of an EPL expression.

On-demand queries are not continuous in nature: The query engine executes the query once and returns all result rows to the application. On-demand query execution is very lightweight as the engine performs no statement creation and the query leaves no traces within the engine.

Esper also provides the facility to explicitly index named windows to speed up queries. Please consult Section 4.15.10, “Explicitly Indexing Named Windows” for more information.

The following limitations apply:

String query = "select * from MyNamedWindow";
EPOnDemandQueryResult result = epRuntime.executeQuery(query);
for (EventBean row : result.getArray()) {
  System.out.println("name=" + row.get("name"));
}

EPOnDemandPreparedQuery prepared = epRuntime.prepareQuery(query);
EPOnDemandQueryResult result = prepared.execute();
// ...later ...
prepared.execute();	// execute a second time

Esper also provides the facility to explicitly index named windows to speed up queries. Please consult Section 4.15.10, “Explicitly Indexing Named Windows” for more information.

An EventType object encapulates all the metadata about a certain type of events. As Esper supports an inheritance hierarchy for event types, it also provides information about super-types to an event type.

An EventType object provides the following information:

For each property of an event type, there is an EventPropertyDescriptor object that describes the property. The EventPropertyDescriptor contains flags that indicate whether a property is an indexed (array) or a mapped property and whether access to property values require an integer index value (indexed properties only) or string key value (mapped properties only). The descriptor also contains a fragment flag that indicates whether a property value is available as a fragment.

The term fragment means an event property value that is itself an event, or a property value that can be represented as an event. The getFragmentType on EventType may be used to determine a fragment's event type in advance.

A fragment event type and thereby fragment events allow navigation over a statement's results even if the statement result contains nested events or a graph of events. There is no need to use the reflection API to navigate events, since fragments allow the querying of nested event properties or array values, including nested CLR types.

When using the Map event representation, any named Map type nested within a Map as a simple or array property is also available as a fragment. When using CLR objects either directly or within Map events, any object that is neither a primitive or boxed built-in type, and that is not an enumeration and does not implement the Map interface is also available as a fragment.

The nested, indexed and mapped property syntax can be combined to a property expression that may query an event property graph. Most of the methods on the EventType interface allow a property expression to be passed.

Your application may use an EventType object to obtain special getter-objects. A getter-object is a fast accessor to a property value of an event of a given type. All getter objects implement the EventPropertyGetter interface. Getter-objects work only for events of the same type or sub-types as the EventType that provides the EventPropertyGetter. The performance section provides additional information and samples on using getter-objects.

An event object is an EventBean that provides:

The GetFragment method on EventBean and EventPropertyGetter return the fragment EventBean or array of EventBean, if the property is itself an event or can be represented as an event. Your application may use EventPropertyDescriptor to determine which properties are also available as fragments.

The underlying event object of an EventBean can be obtained via the Underlying property. Please see Chapter 2, Event Representations for more information on different event representations.

From a threading perspective, it is safe to retain and query EventBean and EventType objects in multiple threads.

Consider a statement that returns the symbol, count of events per symbol and average price per symbol for tick events. Our sample statement may declare a fully-qualified type name as the event type: org.sample.StockTickEvent. Assume that this type exists and exposes a symbol property of type String, and a price property of type (primitive) double.

select symbol, avg(price) as avgprice, count(*) as mycount 
from org.sample.StockTickEvent 
group by symbol

The next table summarizes the property names and types as posted by the statement above:

eventBean.Get["symbol"]

eventBean.Get["avgprice"]

eventBean["mycount"]

A code snippet out of a possible UpdateEventHandler implementation to this statement may look as below:

String symbol = (String) newEvents[0]["symbol"];
double? price = (double?) newEvents[0]["avgprice"];
long? count= (long?) newEvents[0]["mycount"];

The engine supplies the boxed System.Double? and System.Int64? types as property values rather then primitive types. This is because aggregated values can return a null value to indicate that no data is available for aggregation. Also, in a select statement that computes expressions, the underlying event objects to EventBean instances are of type System.Collections.Generic.IDictionary.

Consider the next statement that specifies a wildcard selecting the same type of event:

select * from org.sample.StockTickEvent where price > 100

The property names and types provided by an EventBean query result row, as posted by the statement above are as follows:

eventBean["symbol"]

eventBean["price"]

As an alternative to querying individual event properties via the indexer or Get methods, the Underlying property on EventBean returns the underlying object representing the query result. In the sample statement that features a wildcard-select, the underlying event object is of type org.sample.StockTickEvent:

StockTickEvent tick = (StockTickEvent) newEvents[0].Underlying;

Composite events are events that aggregate one or more other events. Composite events are typically created by the engine for statements that join two event streams, and for event patterns in which the causal events are retained and reported in a composite event. The example below shows such an event pattern.

// Look for a pattern where BEvent follows AEvent
String pattern = "a=AEvent -> b=BEvent";
EPStatement stmt = epService.EPAdministrator.CreatePattern(pattern);
stmt.Events += HandleEvent;

// Example event handler code
  public void HandleEvent(Object sender, UpdateEventArgs e) {
    Console.WriteLine("a event={0}", e.NewData[0]["a"]);
    Console.WriteLine("b event={0}", e.NewData[0]["b"]);
  }

Note that the HandleEvent method can receive multiple events at once encapsulated in the UpdateEventArgs. For example, a time batch window may post multiple events to event handlers representing a batch of events received during a given time period.

Pattern statements can also produce multiple events delivered to update event handlers in one invocation. The pattern statement below, for instance, delivers an event for each A event that was not followed by a B event with the same id property within 60 seconds of the A event. The engine may deliver all matching A events as an array of events in a single invocation of the UpdateEventHandler delegate associated with the statement:

select * from pattern[
  every a=A -> (timer:interval(60 sec) and not B(id=a.id))]

A code snippet out of a possible UpdateEventHandler implementation to this statement that retrives the events as fragments may look as below:

EventBean a = (EventBean) newEvents[0].GetFragment("a");
// ... or using a nested property expression to get a value out of A event...
double value = (double) newEvent[0]["a.value"];

Some pattern objects return an array of events. An example is the unbound repeat operator. Here is a sample pattern that collects all A events until a B event arrives:

select * from pattern [a=A until b=B]

A possible code to retrieve different fragments or property values:

EventBean[] a = (EventBean[]) newEvents[0].GetFragment("a");
// ... or using a nested property expression to get a value out of A event...
double value = (double) newEvent[0]["a[0].value"];

In the default configuration the same application thread that invokes any of the SendEvent methods will process the event fully and also deliver output events to event handlers and subscribers. By default the single internal timer thread based on system time performs time-based processing and delivery of time-based results.

This default configuration reduces the processing overhead associated with thread context switching, is lightweight and fast and works well in many environments such as J2EE, server or client. Latency and throughput requirements are largely use case dependant, and Esper provides engine-level facilities for controlling concurrency that are described next.

Inbound Threading queues all incoming events: A pool of engine-managed threads performs the event processing. The application thread that sends an event via any of the SendEvent methods returns without blocking.

Outbound Threading queues events for delivery to event handlers and subscribers, such that slow or blocking event handlers or subscribers do not block event processing.

Timer Execution Threading means time-based event processing is performed by a pool of engine-managed threads. With this option the internal timer thread (or external timer event) serves only as a metronome, providing units-of-work to the engine-managed threads in the timer execution pool, pushing threading to the level of each statement for time-based execution.

Route Execution Threading means that the thread sending in an event via any of the SendEvent methods (or the inbound threading pooled thread if inbound threading is enabled) only identifies and pre-processes an event, and a pool of engine-managed threads handles the actual processing of the event for each statement, pushing threading to the level of each statement for event-arrival-based execution.

The engine starts engine-managed threads as daemon threads when the engine instance is first obtained. The engine stops engine-managed threads when the engine instance is destroyed via the Dispose method. When the engine is initialized via the Initialize method the existing engine-managed threads are stopped and new threads are created. When shutting down your application, use the Dispose method to stop engine-managed threads.

Note that the options discussed herein may introduce additional processing overhead into your system, as each option involves work queue management and thread context switching.

If your use cases require ordered processing of events or do not tolerate disorder, the threading options described herein may not be the right choice.

If your use cases require loss-less processing of events, wherein the threading options mean that events are held in an in-memory queue, the threading options described herein may not be the right choice.

Care should be taken to consider arrival rates and queue depth. Threading options utilize unbound queues or capacity-bound queues with blocking-put, depending on your configuration, and may therefore introduce an overload or blocking situation to your application. You may use the service provider interface as outlined below to manage queue sizes, if required, and to help tune the engine to your application needs. Consider throttling down the event send rate when the API (see below) indicates that events are getting queued.

All threading options are on the level of an engine. If you require different threading behavior for certain statements then consider using multiple engine instances, consider using the Route method or consider using application threads instead.

Please consult Section 13.4.9, “Engine Settings related to Concurrency and Threading” for instructions on how to configure threading options. Threading options take effect at engine initialization time.

EPServiceProviderSPI spi = (EPServiceProviderSPI) epService;
int queueSize = spi.getThreadingService().getInboundQueue().size();
ThreadPoolExecutor threadpool = spi.getThreadingService().getInboundThreadPool();

With CurrentTimeEvent, as described above, your application can advance engine time to a given point in time. In addition, the NextScheduledTime property in EPRuntime returns the next scheduled time according to started statements. You would typically use CurrentTimeEvent to advance time at a relatively high resolution.

To advance time for a span of time without sending individual CurrentTimeEvent events to the engine, the API provides the class CurrentTimeSpanEvent. You may use CurrentTimeSpanEvent with or without a resolution.

If your application only provides the target end time of time span to CurrentTimeSpanEvent and no resolution, the engine advances time up to the target time by stepping through all relevant times according to started statements.

If your application provides the target end time of time span and in addition a long-typed resolution, the engine advances time up to the target time by incrementing time according to the resolution (regardless of next scheduled time according to started statements).

Consider the following example:

// Set start time to Jan.1, 2010, 00:00 am for this example
DateTime startTime = DateTime.Parse("2010 01 01 00:00:00 000", "yyyy MM dd HH:mm:ss FFF");
runtime.SendEvent(new CurrentTimeEvent(startTime.InMillis()));

// Create a statement.
EPStatement stmt = epService.EPAdministrator.CreateEPL("select current_timestamp() as ct " +
  "from pattern[every timer:interval(1 minute)]");
stmt.Events += ...;	// add an event handler

// Advance time to 10 minutes after start time
runtime.SendEvent(new CurrentTimeSpanEvent(startTime.InMillis() + 10*60*1000));

The above example advances time to 10 minutes after the time set using CurrentTimeSpanEvent. As the example does not pass a resolution, the engine advances time according to statement schedules. Upon sending the CurrentTimeSpanEvent the listener sees 10 invocations for minute 1 to minute 10.

To advance time according to a given resolution, you may provide the resolution as shown below:

// Advance time to 10 minutes after start time at 100 msec resolution
runtime.SendEvent(new CurrentTimeSpanEvent(startTime.getTime() + 10*60*1000, 100));

Consider using the service-provider interface EPRuntimeSPI EPRuntimeIsolatedSPI. The two interfaces are service-provider interfaces that expose additional function to manage statement schedules. However the SPI interfaces should be considered an extension API and are subject to change between release versions.

Additional engine-internal SPI interfaces can be obtained by downcasting EPServiceProvider to EPServiceProviderSPI. For example the SchedulingServiceSPI exposes schedule information per statement (downcast from SchedulingService). Engine-internal SPI are subject to change between versions.

An isolated service allows an application to control event visibility and the concept of time as desired on a statement level: Events sent into an isolated service are visible only to those statements that currently reside in the isolated service and are not visible to statements outside of that isolated service. Within an isolated service an application can control time independently, start time at a point in time and advance time at the resolution and pace suitable for the statements added to that isolated service.

As discussed before, a single application domain may hold multiple Esper engine instances unique by engine URI. Within an Esper engine instance the default execution environment for statements is the EPRuntime engine runtime, which coordinates all statement's reaction to incoming events and to time passing (via internal or external timer).

Subordinate to an Esper engine instance, your application can additionally allocate multiple isolated services (or execution environments), uniquely identified by a name and represented by the EPServiceProviderIsolated interface. In the isolated service, time passes only when you application sends timer events to the EPRuntimeIsolated instance. Only events explicitly sent to the isolated service are visible to statements added.

Your application can create new statements that start in an isolated service. You can also move existing statements back and forth between the engine and an isolated service.

Isolation does not apply to variables: Variables are global in nature. Also, as named windows are globally visibly data windows, consumers to named windows see changes in named windows even though a consumer or the named window (through the create statement) may be in an isolated service.

An isolated service allows an application to:

While a statement resides in an isolated runtime it receives only those events explicitly sent to the isolated runtime, and performs time-based processing based on the timer events provided to that isolated runtime.

Use the GetEPServiceIsolated method on EPServiceProvider passing a name to obtain an isolated runtime:

EPServiceProviderIsolated isolatedService = epServiceManager.GetEPServiceIsolated("name");

Set the start time for your isolated runtime via the CurrentTimeEvent timer event:

// In this example start the time at the system time
long startInMillis = DateTimeHelper.GetCurrentTimeMillis();	
isolatedService.EPRuntime.SendEvent(new CurrentTimeEvent(startInMillis));

Use the AddStatement method on EPAdministratorIsolated to move an existing statement out of the engine runtime into the isolated runtime:

// look up the existing statement
EPStatement stmt = epServiceManager.EPAdministrator.GetStatement("MyStmt");

// move it to an isolated service
isolatedService.EPAdministrator.AddStatement(stmt);

To remove the statement from isolation and return the statement back to the engine runtime, use the RemoveStatement method on EPAdministratorIsolated:

isolatedService.EPAdministrator.RemoveStatement(stmt);

To create a new statement in the isolated service, use the CreateEPL method on EPAdministratorIsolated:

isolatedService.EPAdministrator.CreateEPL(
  "@Name('MyStmt') select * from Event", null, null); 
// the example is passing the statement name in an annotation and no user object

The Dispose method on EPServiceProviderIsolated moves all currently-isolated statements for that isolated service provider back to engine runtime.

When moving a statement between engine runtime and isolated service or back, the algorithm ensures that events are aged according to the time that passed and time schedules stay intact.

To use isolated services, your configuration must have view sharing disabled as described in Section 13.4.11.1, “Sharing View Resources between Statements”.

By adding an existing statement to an isolated service, the statement's processing effectively becomes suspended. Time does not pass for the statement and it will not process events, unless your application explicitly moves time forward or sends events into the isolated service.

First, let's create a statement and send events:

EPStatement stmt = epServiceManager.EPAdministrator.CreateEPL("select * from TemperatureEvent.win:time(30)");
epServiceManager.EPRuntime.Send(new TemperatureEvent(...));
// send some more events over time

The steps to suspend the previously created statement are as follows:

EPServiceProviderIsolated isolatedService = epServiceManager.GetEPServiceIsolated("suspendedStmts");
isolatedService.EPAdministrator.AddStatement(stmt);

To resume the statement, move the statement back to the engine:

isolatedService.EPAdministrator.RemoveStatement(stmt);

If the statement employed a time window, the events in the time window did not age. If the statement employed patterns, the pattern's time-based schedule remains unchanged. This is because the example did not advance time in the isolated service.

This example creates a statement in the isolated service, replays some events and advances time, then merges back the statement to the engine to let it participate in incoming events and engine time processing.

First, allocate an isolated service and explicitly set it to a start time. Assuming that myStartTime is a long millisecond time value that marks the beginning of the data to replay, the sequence is as follows:

EPServiceProviderIsolated isolatedService = epServiceManager.GetEPServiceIsolated("suspendedStmts");
isolatedService.EPRuntime.SendEvent(new CurrentTimeEvent(myStartTime));

Next, create the statement. The sample statement is a pattern statement looking for temperature events following each other within 60 seconds:

EPStatement stmt = epAdmin.CreateEPL(
  "select * from pattern[every a=TemperatureEvent -> b=TemperatureEvent where timer:within(60)]");

For each historical event to be played, advance time and send an event. This code snippet assumes that currentTime is a time greater then myStartTime and reflects the time that the historical event should be processed at. It also assumes historyEvent is the historical event object.

isolatedService.EPRuntime.SendEvent(new CurrentTimeEvent(currentTime));
isolatedService.EPRuntime.Send(historyEvent);
// repeat the above advancing time until no more events

Finally, when done replaying events, merge the statement back with the engine:

isolatedService.EPAdministrator.RemoveStatement(stmt);

When isolating statements, events that are generated by insert into are visible within the isolated service that currently holds that insert into statement.

For example, assume the below two statements named A and B:

@Name('A') insert into MyStream select * from MyEvent
@Name('B') select * from MyStream

When adding statement A to an isolated service, and assuming a MyEvent is sent to either the engine runtime or the isolated service, a listener to statement B does not receive that event.

When adding statement B to an isolated service, and assuming a MyEvent is sent to either the engine runtime or the isolated service, a listener to statement B does not receive that event.

When isolating named windows, the event visibility of events entering and leaving from a named window is not limited to the isolated service. This is because named windows are global data windows (a relation in essence).

For example, assume the below three statements named A, B and C:

@Name('A') create window MyNamedWindow.win:time(60) as select * from MyEvent
@Name('B') insert into MyNamedWindow select * from MyEvent
@Name('C') select * from MyNamedWindow

When adding statement A to an isolated service, and assuming a MyEvent is sent to either the engine runtime or the isolated service, a listener to statement A and C does not receive that event.

When adding statement B to an isolated service, and assuming a MyEvent is sent to either the engine runtime or the isolated service, a listener to statement A and C does not receive that event.

When adding statement C to an isolated service, and assuming a MyEvent is sent to the engine runtime, a listener to statement A and C does receive that event.

Moving statements between an isolated service and the engine is an expensive operation and should not be performed with high frequency.

When using multiple threads to send events and at the same time moving a statement to an isolated service, it its undefined whether events will be delivered to a listener of the isolated statement until all threads completed sending events.

Metrics reporting is not available for statements in an isolated service. Advanced threading options are also not available in the isolated service, however it is thread-safe to send events including timer events from multiple threads to the same or different isolated service.

A EPStatementObjectModel consists of an object graph representing all possible clauses that can be part of an EPL statement.

Among all clauses, the SelectClause and FromClause objects are required clauses that must be present, in order to define what to select and where to select from.

Part of the statement object model package are convenient builder classes that make it easy to build a new object model or change an existing object model. The SelectClause and FromClause are such builder classes and provide convenient Create methods.

Within the from-clause we have a choice of different streams to select on. The FilterStream class represents a stream that is filled by events of a certain type and that pass an optional filter expression.

We can use the classes introduced above to create a simple statement object model:

EPStatementObjectModel model = new EPStatementObjectModel();
model.SelectClause = SelectClause.CreateWildcard();
model.FromClause = FromClause.Create(FilterStream.Create("com.chipmaker.ReadyEvent"));

The model as above is equivalent to the EPL :

select * from com.chipmaker.ReadyEvent

Last, the code snippet below creates a statement from the object model:

EPStatement stmt = epService.EPAdministrator.Create(model);

Notes on usage:

The EPStatementObjectModel includes an optional where-clause. The where-clause is a filter expression that the engine applies to events in one or more streams. The key interface for all expressions is the Expression interface.

The Expressions class provides a convenient way of obtaining Expression instances for all possible expressions. Please consult the SDK documentatin for detailed method information. The next example discusses sample where-clause expressions.

Use the Expressions class as a service for creating expression instances, and add additional expressions via the Add method that most expressions provide.

In the next example we add a simple where-clause to the EPL as shown earlier:

select * from com.chipmaker.ReadyEvent where line=8

And the code to add a where-clause to the object model is below.

model.WhereClause = Expressions.Eq("line", 8);

The following example considers a more complex where-clause. Assume we need to build an expression using logical-and and logical-or:

select * from com.chipmaker.ReadyEvent 
where (line=8) or (line=10 and age<5)

The code for building such a where-clause by means of the object model classes is:

model.WhereClause = Expressions.Or()
  .Add(Expressions.Eq("line", 8))
  .Add(Expressions.And()
      .Add(Expressions.Eq("line", 10))
      .Add(Expressions.Lt("age", 5))
  );

The Patterns class is a factory for building pattern expressions. It provides convenient methods to create all pattern expressions of the pattern language.

Patterns in EPL are seen as a stream of events that consist of patterns matches. The PatternStream class represents a stream of pattern matches and contains a pattern expression within.

For instance, consider the following pattern statement.

select * from pattern [every a=MyAEvent and not b=MyBEvent]

The next code snippet outlines how to use the statement object model and specifically the Patterns class to create a statement object model that is equivalent to the pattern statement above.

EPStatementObjectModel model = new EPStatementObjectModel();
model.SelectClause = SelectClause.CreateWildcard();
PatternExpr pattern = Patterns.And()
  .Add(Patterns.EveryFilter("MyAEvent", "a"))
  .Add(Patterns.NotFilter("MyBEvent", "b"));
model.FromClause = FromClause.Create(PatternStream.Create(pattern));

In this section we build a complete example statement and include all optional clauses in one EPL statement, to demonstrate the object model API.

A sample statement:

insert into ReadyStreamAvg(line, avgAge) 
select line, avg(age) as avgAge 
from com.chipmaker.ReadyEvent(line in (1, 8, 10)).win:time(10) as RE
where RE.waverId != null
group by line 
having avg(age) < 0
output every 10.0 seconds 
order by line

Finally, this code snippet builds the above statement from scratch:

EPStatementObjectModel model = new EPStatementObjectModel();
model.InsertInto = InsertIntoClause.create("ReadyStreamAvg", "line", "avgAge");
model.SelectClause = SelectClause.Create()
    .Add("line")
    .Add(Expressions.Avg("age"), "avgAge");
Filter filter = Filter.Create("com.chipmaker.ReadyEvent", Expressions.In("line", 1, 8, 10));
model.FromClause = FromClause.Create(
    FilterStream.Create(filter, "RE").AddView("win", "time", 10));
model.WhereClause = Expressions.IsNotNull("RE.waverId");
model.GroupByClause = GroupByClause.Create("line");
model.HavingClause = Expressions.Lt(Expressions.Avg("age"), Expressions.Constant(0));
model.OutputLimitClause = OutputLimitClause.Create(OutputLimitSelector.DEFAULT, Expressions.TimePeriod(null, null, null, 10.0, null));
model.OrderByClause = OrderByClause.Create("line");

This sample statement creates a variable:

create variable integer var_output_rate = 10

The code to build the above statement using the object model:

EPStatementObjectModel model = new EPStatementObjectModel();
model.CreateVariable = CreateVariableClause.Create("integer", "var_output_rate", 10));
epService.EPAdministrator.Create(model);

A second statement sets the variable to a new value:

on NewValueEvent set var_output_rate = new_rate

The code to build the above statement using the object model:

EPStatementObjectModel model = new EPStatementObjectModel();
model.OnExpr = OnClause.CreateOnSet("var_output_rate", Expressions.Property("new_rate"));
model.FromClause = FromClause.Create(FilterStream.Create("NewValueEvent"));
EPStatement stmtSet = epService.EPAdministrator.Create(model);

This sample statement creates a named window:

create window OrdersTimeWindow.win:time(30 sec) as select symbol as sym, volume as vol, price from OrderEvent

The is the code that builds the create-window statement as above:

EPStatementObjectModel model = new EPStatementObjectModel();
model.CreateWindow = CreateWindowClause.Create("OrdersTimeWindow");
model.CreateWindow.AddView("win", "time", 30);
model.SelectClause = SelectClause.Create()
		.AddWithName("symbol", "sym")
		.AddWithName("volume", "vol")
		.Add("price");
model.FromClause = FromClause.Create(FilterStream.Create("OrderEvent));

A second statement deletes from the named window:

on NewOrderEvent as myNewOrders
delete from AllOrdersNamedWindow as myNamedWindow
where myNamedWindow.symbol = myNewOrders.symbol

The object model is built by:

EPStatementObjectModel model = new EPStatementObjectModel();
model.OnExpr = OnClause.CreateOnDelete("AllOrdersNamedWindow", "myNamedWindow");
model.FromClause = FromClause.Create(FilterStream.Create("NewOrderEvent", "myNewOrders"));
model.WhereClause = Expressions.EqProperty("myNamedWindow.symbol", "myNewOrders.symbol");
EPStatement stmtOnDelete = epService.EPAdministrator.Create(model);

A third statement selects from the named window using the non-continuous on-demand selection via on-select:

on QueryEvent(volume>0) as query
select count(*) from OrdersNamedWindow as win
where win.symbol = query.symbol

The on-select statement is built from scratch via the object model as follows:

EPStatementObjectModel model = new EPStatementObjectModel();
model.OnExpr = OnClause.CreateOnSelect("OrdersNamedWindow", "win");
model.WhereClause = Expressions.EqProperty("win.symbol", "query.symbol");
model.FromClause = FromClause.Create(FilterStream.Create("QueryEvent", "query", 
  Expressions.Gt("volume", 0)));
model.SelectClause = SelectClause.Create().Add(Expressions.CountStar());
EPStatement stmtOnSelect = epService.EPAdministrator.Create(model);

Engine metrics are properties of EngineMetric events:

Statement metrics are properties of StatementMetric. The properties are:

The totals reported are cumulative relative to the last metric report.

The JSON renderer produces JSON text according to the standard documented at http://www.json.org.

The renderer formats simple properties as well as nested properties and indexed properties according to the JSON string encoding, array encoding and nested object encoding requirements.

The renderer does render indexed properties, it does not render indexed properties that require an index, i.e. if your event representation is backed by native objects and your getter method is getValue(int index), the indexed property values are not part of the JSON text. This is because the implementation has no way to determine how many index keys there are. A workaround is to have a method such as Object[] getValue() instead.

The same is true for mapped properties that the renderer also renders. If a property requires a Map key for access, i.e. your getter method is getValue(String key), such property values are not part of the result text as there is no way for the implementation to determine the key set.

The XML renderer produces well-formed XML text according to the XML standard.

The renderer can be configured to format simple properties as attributes or as elements. Nested properties and indexed properties are always represented as XML sub-elements to the root or parent element.

The root element name provided to the XML renderer must be the element name of the root in the XML document and may include namespace instructions.

The renderer does render indexed properties, it does not render indexed properties that require an index, i.e. if your event representation is backed by native objects and your getter method is GetValue(int index), the indexed property values are not part of the XML text. This is because the implementation has no way to determine how many index keys there are. A workaround is to have a method such as Object[] GetValue() instead.

The same is true for mapped properties that the renderer also renders. If a property requires a Map key for access, i.e. your getter method is GetValue(String key), such property values are not part of the result text as there is no way for the implementation to determine the key set.