Esper-8

In Esper-8, we removed the runtime configuration API namely ConfigurationOperations and EPAdministrator#getConfiguration. The methods therein duplicated regular configuration and are available using EPL instead.

In Esper-8, we removed timer control events. The TimerEvent class and its subclasses are removed. Please use EPEventService#advanceTime, EPEventService#advanceTimeSpan, EPEventService#clockInternal and EPEventService#clockExternal instead.

In Esper-8, we removed support for revision event types. They were generally superseded by tables and update.

In Esper-8, we removed support for plug-in event representations. Implementing custom event type with a compiler architecture means an event type must be able to generate lots of small pieces of code. And implementing an event type requires a lots of plug-in code before that. The feature seemed un-used also because the existing event types offer all that is needed.

In Esper-8, we removed the the view resources configuration settings "Sharing View Resources Between Statements" and "Multi-Expiry Policy". The former was set to false by default. Named windows already to a way better job at sharing vies. The latter provided compatibility for those migrating from version 3 and was thus outdated.

In Esper-8, we removed support for updating event types and removing event types via API. We plan on being able to update modules. Please contact us if you are interested.

In Esper-8, we removed EsperIO-Stax. EsperIO-Stax was an example for plug-in event representations (see above).

In Esper-8, we removed support for isolated service providers. This feature was limited to non-sharable EPL objects since EPL objects such as named windows or tables were always global.

There are no EPL changes between Esper-7 and Esper-8 other than as documented below. The execution of EPL is the same between the versions.

URI Use in EPL

Esper-7 allowed the use of the engine-URI to be used as a prefix to the event property name in expressions. Since in Esper-8 the runtime-URI is not available to the compiler the URI cannot be specified any longer as part of an event property expression.

Automated Bean Event Type Registration when the From-Clause Provided a Fully-Qualified Class Name

In Esper-7 when the from-clause or on-clause had a fully-qualified class name Esper-7 would create an event type for the class implicitly. Esper-8 does not automatically create an event type for the from-clause and on-clause. In Esper-8 the from-clause or on-clause must refer to existing event type. You may however register an event type with an event type name that is the fully-qualified class name.

Substitution Parameters

In Esper-7 the type of the substitution parameter was known before EPL query validation since the call to set a value took place before query validation. In Esper-8 the type of the substitution parameter is not known since setting a value takes place at runtime. In Esper-8 the compiler assumes Object-type for substitution parameters in case the EPL does not provide a type. This can cause your EPL to not compile. You can either provide the type of the substitution parameter using ?::type or ?:name:type. Or you can use the cast function to cast to the desired type.

Named Window Subquery Index Sharing

Subquery index sharing for named windows now requires creating an explicit index using create index. In Esper-7 the query planner, when using named window subquery index sharing, would know about indexes already created by other modules. In Esper-8 the compiler does not know implicit indexes created by other modules therefore named window subquery index sharing relies on indexes created using create index only.

The instructions herein are meant to be used together with the remaining material on migrating. They provide an outline for moving an application to Esper 8.

Classpath Changes

Remove CGLib from classpath. Add the Esper compiler, common and runtime jar files and their dependencies.

Configuration Changes

Please see the document on migrating configuration XML and configuration code.

The following settings are for applications that allow subscribers and that rely on the Esper-7 global public visibilities.

The XML configuration is:

<esper-configuration xmlns="https://www.espertech.com/schema/esper">
    <compiler>
		<bytecode
                allow-subscriber="true"
                access-modifier-context="public"
                access-modifier-event-type="public"
                access-modifier-expression="public"
                access-modifier-named-window="public"
                access-modifier-script="public"
                access-modifier-table="public"
                access-modifier-variable="public"
                bus-modifier-event-type="bus"/>
    </compiler>
</esper-configuration>

The code for using the configuration API is:

Configuration configuration = new Configuration();
configuration.getCompiler().getByteCode().setAllowSubscriber(true);
configuration.getCompiler().getByteCode().setAccessModifiersPublic();
configuration.getCompiler().getByteCode().setBusModifierEventType(EventTypeBusModifier.BUS);

By setting the allow-subscriber flag your statement allows subscribers to receive results. Esper-7 allows subscribers by default.

By setting the default access modifiers to PUBLIC all EPL-objects such as event types are publicly visible. Esper-7 has only public visibility.

By setting the bus-modifier for event types to BUS your application can use send-event to send any type of event into the engine. Esper-7 has only bus visibility.

Remove Esper-related Imports from Classes

All package names have changed due to the refactoring into common, compiler and runtime. Please remove all Esper-related imports from the import section of each class.

Classes in com.espertech.esper.client that were common to the compiler and runtime have been moved to com.espertech.esper.common.client, for example EventBean and EventType.

Classes in com.espertech.esper.client that were specific to the runtime have been moved to com.espertech.esper.runtime.client.

Compile-Related Changes

Esper-8 uses a compiler for compiling an EPL module to byte code. The Esper-7 createEPL method has been removed. You could use the utility method shown below for compiling. It returns you a Deployment object. Use deployment.getStatements() to obtain the EPStatement instances.

Here is a method that can replace createEPL calls of Esper-7:

public static EPDeployment compileDeploy(EPRuntime runtime, String epl) {
  try {
    // Obtain a copy of the engine configuration
    Configuration configuration = runtime.getConfigurationDeepCopy();

    // Build compiler arguments
    CompilerArguments args = new CompilerArguments(configuration);

    // Make the existing EPL objects available to the compiler
    args.getPath().add(runtime.getRuntimePath());

    // Compile
    EPCompiled compiled = EPCompilerProvider.getCompiler().compile(epl, args);

    // Return the deployment
    return runtime.getDeploymentService().deploy(compiled);
  }
  catch (Exception ex) {
    throw new RuntimeException(ex);
  }
}

Here is how to use the method above:

EPDeployment deployment = compileDeploy(runtime, epl);
deployment.getStatements()[0].addListener(...);

Change Listener Code

The StatementAwareUpdateListener interface has been removed. Instead the UpdateListener interface was changed to match the StatementAwareUpdateListener
footprint.

Change Calls to the EPRuntime#sendEvent method

The send-event and route-event methods were moved to the EPEventService interface and were renamed to consistently account for the underlying event object
to be processed. All methods now also require the event type name as a parameter. The new methods are sendEventBean, sendEventMap, sendEventObjectArray,
sendEventXMLDOM and sendEventAvro.

For example:

runtime.getEventService().sendEventBean(new MyEvent(...), "MyEvent");

Change Code That Advances Time

The TimerEvent class is removed and the sendEvent method can no longer be used to advance time. Use EPEventService#advanceTime(time) and EPEventService#clockExternal() instead.

Change Code That Uses the Runtime Configuration API

The ConfigurationOperations interface has been removed. Instead use the Configuration interface or respective service such as EPVariableService.

This page provides per-interface information on the API changes. It lists the Esper-7 class name and underneath it lists all removed methods, all changed methods and all new methods. When there were no changes for a method or interface the document does not list the method or interface.

The document lists the key public methods of Esper-7 and does not list extension APIs, software provider (SPI) interfaces and other utility classes.

EPServiceProviderManager

This class has been renamed to EPRuntimeProvider.

EPServiceProvider

This class has been renamed to EPRuntime.

EPRuntime

This class has been renamed to EPEventService.

EPAdministrator

This class has been renamed to EPDeploymentService.

EPStatement

EPContextPartitionAdmin

The class EPContextPartitionAdmin has been renamed to EPContextPartitionService.
Obtain from EPRuntime#getContextPartitionService.

EPDataFlowRuntime

The class EPDataFlowRuntime has been renamed to EPDataFlowService.
Obtain from EPRuntime#getDataFlowService.

EPDeploymentAdmin

This class has been superseded by the compiler API and there is no direct replacement.

ConfigurationOperations

This class has been superseded by other APIs and by using EPL.

EPVariableService

The methods of EPRuntime (old API) that are related to variables have been moved to this class.
Obtain from EPRuntime#getVariableService.

EPOnDemandPreparedQuery

This class was renamed to EPFireAndForgetPreparedQuery.

EPOnDemandPreparedQueryParameterized

This class was renamed to EPFireAndForgetPreparedQueryParameterized.

EPOnDemandQueryResult

This class was renamed to EPFireAndForgetQueryResult.

Statement Object Model API Changes

The changes in the statement object model classes between Esper-8 and Esper-7 are:

Introduction

Configuration now has 3 sections:

1. Common section: All configuration common to the compiler and the runtime
2. Compiler section: Configuration that applies to the compiler only
3. Runtime section: Configuration that applies to the runtime only

The compiler ignores the runtime section of the configuration, and the runtime ignores the compiler section of the configuration.

Configuration Object Class and Package Name

Esper-8 moved configuration classes to com.espertech.esper.common.client.configuration and the common, compiler and runtime packages.

Esper-8 renamed configuration classes. A table of renamed classes can be found below. Certain configuration inner classes have been moved to com.espertech.esper.common.client.util.

Migrating XML files

The new schema is esper-configuration-8-0.xsd .

NOTE: The new schema is not compatible with the version 7 schema.

The new schema moves all configuration to <common>, <compiler> and <runtime> elements.

EsperTech provides an online cloud-based application that can read an existing Esper-7 XML configuration and produce an Esper-8 XML configuration. The link is http://esper-config-upgrade7to8.appspot.com.
The class that provides the functionality is com.espertech.esper.common.client.configuration.ConfigurationSchema7To8Upgrade.

Table of Updates

The below table is structured by configuration topic. Within the topic the table describes into which section (common, compiler, runtime) the configuration moves.

In some cases, specifically for engine settings, multiple sections may apply. In this case the table provides instructions which subset of properties belongs to which section.

Removed Configuration

• The view resources configuration removes the share-views setting and the allow-multiple-expiry-policy setting.
• The execution configuration removes the allow-isolated-service setting.
• The runtime threading engine-fairlock is now runtime-fairlock.
• The runtime metrics reporting engine-interval is now runtime-interval.
• The runtime metrics reporting jmx-engine-metrics is now jmx-runtime-metrics.
• The HA-configuration enginelock-settings is now runtimelock-settings.

This section overviews conceptual changes and is not an all-inclusive statement of changes. It is intended to provide background information.

Removed CGLIB Dependency

As the compiler generates all the byte code to access event properties and call methods we removed the CGLIB library as a dependency entirely.

ANTLR Jar Dependency Only at Compile-Time

Only the compiler needs the ANTLR library and the runtime does not need ANTLR anymore. The only dependency of the runtime is the SLF4J library.

Public API Names

In Esper 8 the compiler and runtime and replace the service provider of Esper 7. The term "service provider" and "engine" were thus replaced by runtime. The resulting name changes in the public API are substantial. Some of the renamed classes are listed below. Please consult the API-migration doc for a table on impacted classes.

• EPServiceProviderManager is now EPRuntimeProvider
• EPServiceProvider is now EPRuntime
• EPRuntime is now EPEventService
• EPAdministrator is now EPDeploymentService

Names for Statements, Event Types, Named Windows, Tables, Variables, Contexts, Expressions, Scripts and Indexes

The compiler does not have access to deployment-time names and therefore cannot determine whether a name is already used or not.

For example, an EPL module defines a statement by name "A" using "@name('A')". The statement name may already be used by another statement in the runtime environment. In Esper-7 a statement name was unique across the runtime and Esper-7 simply generated a new statement name. Generating a new name however is not an option for variable names, context names, named window names and others.

Therefore in Esper-8 a name is unique in combination with the deployment-id. This is true for all names such as statement name, context name, variable name and others.

For example, an EPL module may define a statement by name "A". The compiler compiles the module to byte code. The runtime deploys the byte code using deployment id 'D1'. The statement is uniquely named as a combination of deployment id and statement name. The combined key is {deploymentId='D1', statementName='A'}.

This change meant that all APIs that handle names must take the deployment id as an additional parameter or must return the deployment id as part of the result. Your application must iterate and find statements using deployment ids.

EPL Module as the Source Code Unit

EPL modules consist of EPL statements. The compiler compiles EPL modules to byte code and you can deploy that byte code to the runtime. Any single EPL statement must be part of a module for compiling and deploying.

Esper-8 thus removes the single EPL statement as a unit and removes the "createEPL" methods for creating a single statement. It also removes the statement lifecycle, therefore the statement "stop", "start" and "destroy" methods are removed. They are replaced by "deploy" and "undeploy" for byte code and deployment lifecycle.

Configuration

The compiler and runtime are now completely separated. This meant that the configuration that applies to the compiler needed to be separated from the configuration that applies to the runtime. There are some common parts to configuration that can apply at compile-time and at runtime.

Keeping one configuration object that contains a common, a compiler and a runtime configuration is easiest to use. It however means that existing configuration must all migrate to one of the 3 sections.

In effect this means the configuration XML now has a <common>, <compiler> and <runtime>. In turn the configuration class offers Configuration#getCommon, Configuration#getCompiler and Configuration#getRuntime.

Bean Event Types

One of the issues that users of Esper-7 had trouble with was the fact that Esper-7 identified Bean-style event types by class disallowing use of the same class to represent multiple event types without subclassing. Esper-8 identifies a Bean-style event type by name that consistent with all other event types.

In Esper-7 the from-clause could specify a full-qualified or otherwise resolvable class name and Esper-7 would dynamically allocate a bean event type for the same fully-qualified class name. With the compiler architecture this behavior would cause implicit type references.

In Esper-8 all event types are either preconfigured or allocated using create schema or insert into.

Duplicate Listener Interfaces

In Esper-7 there were two types of listeners. Esper-8 simplifies the listener interface into a single UpdateListener interface.

Subscribers

As the compiler produces byte code for delivering results to subscribers, that byte code is unnecessary for applications that don't use subscribers. In Esper-8 there is a new setting to control whether the compile produces byte code for subscribers.

Substitution Parameters

In many cases the compiler must know the type of the substitution parameter to ensure type-safety. Therefore Esper-8 supports a type name for substitution parameters, using "?:name:type". The compiler must assume Object-type in case the EPL does not provide a type.