www.espertech.comDocumentation

Chapter 1. Getting Started

1.1. Introduction to CEP and event series analysis
1.2. Steps
1.2.1. Step One: Setting up Classpath
1.2.2. Step Two: Obtain Engine Instance
1.2.3. Step Three: Provide Information on Input Events
1.2.4. Step Four: Create EPL Statements and Attach Callbacks
1.2.5. Step Five: Send Events
1.3. Required 3rd Party Libraries

The Esper engine has been developed to address the requirements of applications that analyze and react to events. Some typical examples of applications are:

What these applications have in common is the requirement to process events (or messages) in real-time or near real-time. This is sometimes referred to as complex event processing (CEP) and event series analysis. Key considerations for these types of applications are throughput, latency and the complexity of the logic required.

The Esper engine was designed to make it easier to build and extend CEP applications.

More information on CEP can be found at FAQ.

Your application can register an event type to instruct the engine what the input events look like. When creating EPL statements the engine checks the available event type information to determine that the statement is valid.

This example assumes that there is a Java class PersonEvent and each instance of the PersonEvent class is an event. Note that it is not necessary to create classes for each event type, as explained below. Here is the class:

package com.mycompany.myapp;

public class PersonEvent {
  private String name;
  private int age;

  public PersonEvent(String name, int age) {
    this.name = name;
    this.age = age;
  }

  public String getName() {
    return name;
  }

  public int getAge() {
    return age;
  }
}

Your application can call the addEventType method that is part of the runtime configuration interface to tell the engine about the PersonEvent class:

engine.getEPAdministrator().getConfiguration().addEventType(PersonEvent.class);

Upon calling the addEventType method and passing the PersonEvent class the engine inspects the class using reflection and determines the event properties. Because the class has two JavaBean-standard getter-methods the engine determines that a PersonEvent has two properties: the name property of type string and the age property of type int.

Now that the PersonEvent event type is known to the engine, your application can create EPL statements that have PersonEvent in the from-clause and EPL can refer to event property names.

Instead of PersonEvent being a Java class, it could also be an Apache Avro schema or an XML schema or a Map or array of names and properties. The different event representations are discussed at Section 2.5, “Comparing Event Representations”.

Your application can instead pre-configure event types using the Configuration object, see Section 16.4, “Configuration Items”.

Your application can, instead of calling an API, add event types using EPL with create schema, see Section 5.15, “Declaring an Event Type: Create Schema”.

The sample EPL for this getting-started section simply selects the name and the age of each arriving person event:

select name, age from PersonEvent

Your application can create an EPL statement using the createEPL method that is part of the administrative interface.

The API calls are:

String epl = "select name, age from PersonEvent";
EPStatement statement = engine.getEPAdministrator().createEPL(epl);

Upon creating the statement, the engine verifies that PersonEvent exists since it is listed in the from-clause. The engine also verifies that the name and age properties are available for the PersonEvent since they are listed in the select-clause.

After successful verification, the engine internally adds an entry to an internally-maintained reverse index tree structure that ensures that when a PersonEvent comes in it will be processed by the statement.

Your application can attach a callback to the EPStatement to receive statement results.

The following callback simply prints name and age:

statement.addListener( (newData, oldData) -> {
  String name = (String) newData[0].get("name");
  int age = (int) newData[0].get("age");
  System.out.println("String.format(Name: %s, Age: %d", name, age));
});

More information about creating EPL statements is at Section 15.3.1, “Creating Statements” and Section 17.6, “The Deployment Administrative Interface” and the JavaDoc.

Your application can provide different kinds of callbacks, see Section 15.3.2, “Receiving Statement Results”.

Your application can send events into the engine using the sendEvent method that is part of the runtime interface:

engine.getEPRuntime().sendEvent(new PersonEvent("Peter", 10));

The output you should see is:

Name: Peter, Age: 10

Upon sending the PersonEvent event object to the engine, the engine consults the internally-maintainced shared reverse index tree structure to determine if any EPL statement is interested in PersonEvent events. The EPL statement that was created as part of this example has PersonEvent in the from-clause, thus the engine delegates processing of such events to the statement. The EPL statement obtains the name and age properties by calling the getName and getAge methods.

For different event representations and sendEvent methods please see Section 2.5, “Comparing Event Representations”.

Specialized event senders are explained in Section 15.4.1, “Event Sender”.

For reference, here is the complete code without event class:

EPServiceProvider engine = EPServiceProviderManager.getDefaultProvider();
engine.getEPAdministrator().getConfiguration().addEventType(PersonEvent.class);
String epl = "select name, age from PersonEvent";
EPStatement statement = engine.getEPAdministrator().createEPL(epl);
statement.addListener( (newData, oldData) -> {
  String name = (String) newData[0].get("name");
  int age = (int) newData[0].get("age");
  System.out.println(String.format("Name: %s, Age: %d", name, age));
});
engine.getEPRuntime().sendEvent(new PersonEvent("Peter", 10));

Esper requires the following 3rd-party libraries at runtime:

Esper requires the following 3rd-party libraries for running the test suite: