This page contains instructions for migrating an application developed against Esper version 2.0 or 2.1 or 2.2 or 2.3 to version 3.

Esper version 3 is a milestone release that adds important new features as well as incorporates various changes aimed at making the engine and EPL easier to use and more consistent, as well as retiring deprecated constructs.

For a list of new features, please consult the change history.

Version 3 JAR file dependencies

We have upgraded jar file dependencies from version 2.x to version 3.0.

Between minor releases of versions 1.x and versions 2.x, we have held the version of dependent jar files constant to provide stability.

Version 3 relies on updated versions of the same set of dependencies as 2.x versions. We plan to have all Esper 3.x releases have the same dependency list as shown below.

Version 2.x depended on ANTLR 3.01, Log4J 1.2.14 and CGLib 2.1_3.

Public API Changes

EventType and EventBean moved to client package

Version 3 consolidates all public API (exclusive the extension API) into a single package under

.

In version 2.x the interfaces com.espertech.esper.event.EventType and com.espertech.esper.event.EventBean were part of the public API while the remainder of the com.espertech.esper.event package was not part of the public API. The EventType and EventBean interfaces have therefore been moved into com.espertech.esper.client.

The exception classes PropertyAccessException and EPStatementSyntaxException have also moved to the client package.

Minor Configuration API Method Changes

Esper version 3 retires the term "alias" for event types and simply uses the term "name" or "event type name" instead. This change results in a few minor changes to methods in com.espertech.esper.client.Configuration and com.espertech.esper.client.ConfigurationOperations.

The following methods in com.espertech.esper.client.Configuration were renamed:

• method "addEventTypeAlias" is now "addEventType"
• method "isEventTypeAliasExists" is now "isEventTypeExists"
• method "addEventTypeAutoAlias" is now "addEventTypeAutoName"
• method "setPlugInEventTypeAliasResolutionURLs" is now "setPlugInEventTypeResolutionURLs"
• method "getEventTypeAliasUsedBy" is now "getEventTypeNameUsedBy"

In addition, Esper version 3 allows Map event types to contain nested Map event types. Thereby the "addEventType" method now takes "Map<String, Object>" as a parameter while version 2.x took Map<String, Class>,  and the method  "addEventTypeAliasNestable" has been removed.

Minor XML Configuration Schema Changes

Esper version 3 retires the term "alias" for event types and simply uses the term "name" or "event type name" instead. This change results in a few minor changes to xml elements in the XML schema file esper-configuration-3-0.xsd.

Please migrate the schema version reference in your XML configuration file to version 3, and validate the XML configuration file against the version 3 schema in the "etc" folder of the distribution or from http://www.espertech.com/schema/esper/esper-configuration-3-0.xsd

Changes to EPL Syntax or Semantics

Division yields double-typed result

Following Java conventions, Esper in version 2.x performed integer division if both operands to a division were non-floating types.

For example, the query

returned a zero value in Esper 2.x.

In version 3, we have decided to follow SQL standard conventions instead and changed division to return double-typed values. The above query in version 3.0 returns double-typed 0.5  as a result. For backward compatibility, integer division can be enabled through configuration.

View and Pattern Object Parameterization

As Esper version 3 supports passing expressions as view parameters, the string constant notation for view parameters is no longer supported.

The following statement is invalid in Esper 3.0:

Please replace the syntax with the following, which Esper 2.x supports as well:

The reason is that the text "'field'" denotes a string constant and not a property name.

Join Statement Requires Data Window

Esper version 3 validates that streams in a join specify a data window. Esper version 2.x defaulted to keep-all semantics in case no data window is specified.

The following statement is not valid in version 3 as no data window is provided:

Version 3 requires that you specify a data window, for example:

There are certain exceptions when no data window is required, such as for named windows, self-joins, unidirectional joins and polling (database or method) joins.

Multiple Data Windows

In Esper 3, when using multiple data windows for a given stream, the engine now applies set-intersection semantics by default and set-union semantics if the new "retain-union" keyword is provided.

In Esper 2.x, multiple data windows combined for a stream is a feature for advanced users, and semantics depended on the order in which data windows were listed.

For example in version 3, this statement retains the intersection of the last 10 minutes of unique RFID events per asset id:

Subquery Order of Evaluation

Esper version 3 guarantees a well-defined order in which subqueries are evaluated. Consider the following query that looks for the same event inside a subquery and outside the subquery:

By default, on arrival of MyEvent, in Esper version 3 the subquery's data window gets updated before the where-clause evaluates thereby above query will not return a result. This behavior is configurable. In version 2.x the behavior was undefined and could vary depending on filters.

Widening of Float and Long returns Double

Esper version 3 when a widening is required between a float-typed value and a long-typed value then the result is a double-typed value. Esper 2.x returned a float-type value.

Null-Values Handling

Esper version 3 strictly follows SQL standards in regards to Null value handling.

In Esper version 3, following SQL standards, the relational operator when used with a null value returns null, while in release 2.x the value returned was true or false which was not according to SQL standards.

For example:

Esper version 3 returns Null for the above query if property is a null value, while version 2.x returned false.

In Esper version 3 the IN-operator, if there are no successes and at least one right-hand row yields null, the result of the IN will be null, not false. This is in accordance with SQL's normal rules for Boolean combinations of null values.

For example:

Version 3 returns Null for the above query if property is a null value, while version 2.x returned false interpreting Null as a regular value.

XML DOM event representation and indexed properties

When using the XML DOM event representation, the property expression "indexprop[1]" resulted in the first property value returned from the array (repeated element nodes).
Esper version 3 corrects the behavior such that the property expression now returns the second value in an array, while "indexprop[0]" returns the first value.

Deprecated and Removed

Removed "stat:cube" view

The stat:cube view was removed from version 3.0. The aggregation functions and grouping made this view obsolete.

Removed EmittedListener and emit method

Version 3 removes the com.espertech.esper.client.EmittedListener from the API. Also removed from EPRuntime are the emit methods.
The emit method and emitted event listeners we not deemed part of the core Esper functionality and were not coupled to the engine.
They have been therefore been removed.

Removed examples

We have removed the RSI, ATM and road toll examples. We have instead added new examples and restructured example directories.

Extension API Changes

Changes in the extension API are only relevant to applications that provide their own view or pattern object, or a plug-in event type.

In version 3, the parameters to views and pattern objects are now expressions themselves. Thereby the extension API needed to be changed to accommodate passing any expression as a parameter to a view or pattern object.

In version 3 the EventType interface has changed to provide property descriptor objects (EventPropertyDescriptor) and methods for fragment events and fragment event types.

Please review the extension API documentation for release 3.0.