An event can be represented by a JSON-formatted string value. Event properties of JSON events are the properties of the JSON object.

The advantages for supporting JSON as an event representation are:

Similar to the Map and object-array event type, the JSON event type takes part in the comprehensive type system that can eliminate the need to use Java classes as event types.

The runtime can process string-value events that are formatted JSON documents via the sendEventJson(String json, String jsonEventTypeName) method on the EPEventService interface.

The runtime does not validate JSON events. Your application must ensure that the JSON object matches the declaration of the schema in create json schema.

A given JSON event type can have only a single supertype that must also be a JSON event type. All properties available on the JSON supertype are also available on the type itself. In addition, anywhere within EPL that an event type name of a JSON supertype is used, the JSON subtype and the subtype of the subtype match that expression.

The Esper JSON parser produces an event object that is available to your application. The event object implements the JsonEventObject interface (package com.espertech.esper.common.client.json.util). The JsonEventObject extends Map<String, Object> allowing you to use event objects that are originating from JSON like any map.

In order to use JSON for incoming events, the event type name and JSON schema, if available, must be made known via the create json schema EPL syntax. Please see examples in Section 5.15, “Declaring an Event Type: Create Schema”.

In the case that you don't want to define fields using EPL create json schema, you may specify an application class that provides the JSON schema. Please refer to Section G.10, “Customizing the JSON Event Class”.

The code snippets below define a JSON event type, create a JSON event and send the event into the runtime. The sample defines the CarLocUpdateEvent event type. The @public means the event type has public visibility and the @buseventtype means your application can use sendEventJson for this event type.

@public @buseventtype create json schema CarLocUpdateEvent(carId string, direction int)

The CarLocUpdateEvent can now be used in a statement:

select count(*) from CarLocUpdateEvent(direction = 1)#time(1 min)

The sample code to send an event is:

String event = "{" +
  "  \"carId\" : \"A123456\",\n" +
  "  \"direction\" : 1\n" +
  "}";
runtime.getEventService().sendEventJson(event, "CarLocUpdateEvent");

JSON allows objects to be nested within other objects. Each JSON object may itself contain further JSON objects or arrays of JSON objects.

For example, consider the following JSON document:

{ 
  "isbn": "123-456-222",  
  "author": 
    {
      "lastname": "Doe",
      "firstname": "Jane"
    },
  "editor": 
    {
      "lastname": "Smith",
      "firstname": "Jane"
    },
  "title": "The Ultimate Database Study Guide",  
  "category": ["Non-Fiction", "Technology"]
 }

The author and editor objects are nested objects. Please define the schema for nested objects first, and the schemas that are building on the nested schemas thereafter.

Define the schemas as follows:

create json schema Names(lastname string, firstname string);
@public @buseventtype create json schema BookEvent(isbn string, author Names, editor Names, title string, category string[]);

This sample EPL outputs the isbn and the last name of the author and the editor, as well as the first category (use sendEventJson(json, "BookEvent") to process the document):

select isbn, author.lastname as authorName, editor.lastname as editorName, 
  category[0] as firstCategory from BookEvent

The next example JSON document is meant to demonstrate nested objects and arrays of objects:

{
  "id": "0001",
  "type": "donut",
  "name": "Cake",
  "batters": 	
  {
    "machine": "machine A",
    "batter":
    [
      { "id": "1001", "type": "Regular" },
      { "id": "1002", "type": "Chocolate" },
      { "id": "1003", "type": "Blueberry" },
      { "id": "1004", "type": "Devil's Food" }
    ]
  },
  "topping":
  [
    { "id": "5001", "type": "None" },
    { "id": "5002", "type": "Glazed" },
    { "id": "5005", "type": "Sugar" },
    { "id": "5007", "type": "Powdered Sugar" }
  ]
}

Define the schemas as follows:

create json schema IdAndType(id string, type string);
create json schema Batters(machine string, batter IdAndType[]);
@public @buseventtype create json schema CakeEvent(id string, type string, name string, batters Batters, topping IdAndType[]);

The following EPL outputs the name, the batter machine, type of the first batter and the type of the first topping, the count of batters, and the count of toppings of cake events (use sendEventJson(json, "CakeEvent") to process the document):

select name, batters.machine as batterMachine, batters.batter[0].type as firstBatterType,
  topping[0].type as firstToppingType, batters.batter.countOf() as countBatters,
  topping.countOf() as countToppings from CakeEvent

The create json schema EPL specifies the name and type of each event property. The create json schema may also specify no event properties or only a subset of all available event properties. When there are JSON properties that are not known at time of compilation, please see Section G.6, “JSON Dynamic Event Properties”.

The table below shows the supported types and provides links to more information. Types not listed below are not supported for use with a JSON event type.

@public @buseventtype create json schema MyEvent(intValue int)

{ "intValue": 1 }

{ "intValue": "2" }

{ "intValue": null }

{}

{ "intValue": "some text" }

{ "intValue" : ...anything but above, such as JSON array or JSON object... }

@public @buseventtype create json schema MyEvent(booleanValue boolean)

{ "booleanValue": true }

{ "booleanValue": false }

{ "booleanValue": "true" }

{ "booleanValue": "false" }

{ "booleanValue": null }

{}

{ "booleanValue": "some text" }

{ "booleanValue" : ...anything but above, such as JSON array or JSON object... }

@public @buseventtype create json schema MyEvent(stringValue string)

{ "stringValue": "abc" }

{ "stringValue": 1 }

{ "stringValue": false }

{ "stringValue": null }

{}

{ "stringValue" : ...anything but above, such as JSON array or JSON object... }

@public @buseventtype create json schema MyEvent(jsonObject java.util.Map)

{ "jsonObject": {} }

{ "jsonObject": { "property-one": 1, "property-two": "abc" }}

{ "jsonObject": null }

{}

{ "jsonObject" : ...anything but an object... }

@public @buseventtype create json schema MyEvent(jsonArray Object[])

{ "jsonArray": [] }

{ "jsonArray": [ "value-one", 1 ] }

{ "jsonArray": null }

{}

{ "jsonArray" : ...anything but an array... }

@public @buseventtype create json schema MyEvent(jsonValue Object)

{ "jsonValue": {} }

{ "jsonValue": { "property-one": 1, "property-two": "abc" }}

{ "jsonValue": [] }

{ "jsonValue": [ "value-one", 1 ] }

{ "jsonValue": 1 }

{ "jsonValue": "abc" }

{ "jsonValue": true }

{ "jsonValue": null }

{}

The event properties that are known in advance can be listed as part of create json schema. Since the name and type is known the EPL compiler can verify EPL statements that use the predefined properties in expressions. See Section G.4, “JSON Supported Types”.

Event properties for which the property name is known but the type is not known can be defined as one of the untyped types Object (for any JSON value), Object[] (for any JSON array) or Map (for any JSON object) which will provide nested values, arrays and objects; As for instance described at Section G.4.6, “Object Type for Holding an Untyped JSON Value (Any JSON Value)”.

Add @JsonSchema(dynamic=true) to create schema so that the JSON parser parses and the event object keeps all properties available in the JSON document.

The EPL dynamic properties allow using properties in expressions that are not predefined. Please refer to Section 3.3, “Dynamic Event Properties”. The dynamic JSON properties are also available in the JsonEventObject event object for use by application code.

The following table outlines the object type for each JSON value:

@JsonSchema(dynamic=true) @public @buseventtype create json schema SensorEvent()

{
"entityID":"cd9f930e",
"temperature" : 70,
"status" : true,
"entityName":{
  "english":"Cooling Water Temperature"
},
"vt":["2014-08-20T15:30:23.524Z"],
"flags" : null
}

select entityID? as entityId, temperature? as temperature, status? as status, 
    entityName? as entityName, vt? as vt, flags? as flags from SensorEvent

select entityName?.english as englishEntityName from SensorEvent

select * as englishEntityName from SensorEvent

@JsonSchema(dynamic=true) @public @buseventtype create json schema SensorEvent(entityID string)

Esper provides an API to parse the JSON text without processing the event. This is done by following these steps:

For instance, the below EPL declares the CarLocUpdateEvent event type:

@public @buseventtype create json schema CarLocUpdateEvent(carId string, direction int)

Obtain the EventSenderJson like so:

EventSenderJson sender = (EventSenderJson) runtime.getEventService().getEventSender("CarLocUpdateEvent");

The parse method returns the populated event object.

JsonEventObject eventObject = sender.parse(json);

The returned object implements the JsonEventObject interface which extends Map<String, Object>. The interface provides additional methods for writing JSON. Please see the JavaDoc for more information.

Esper includes a shaded copy of the MinimalJson library in package com.espertech.esper.common.client.json.minimaljson (MIT license, see https://github.com/ralfstx/minimal-json/blob/master/LICENSE). MinimalJson provides the base parser. The Esper EPL compiler generates a specific JSON parser class that internally uses MinimalJson.

MinimalJson allows your application to build JSON text using the API. Please consult the JavaDoc for more information. A short example is provided below:

JsonObject jsonObject = new JsonObject().add("carId", "A123456").add("direction", 1);
String json = jsonObject.toString();

Use the @JsonSchemaField annotation to customize how the runtime deserializes (parses from JSON) a given event property and serializes (writes as JSON) a given event property.

The @JsonSchemaField annotation can be used with create json schema and also applies to @EventRepresentation('json') for use with insert into or create window.

The name value of @JsonSchemaField provides the event property name. The adapter property provides the class name of the class that implements the JsonFieldAdapterString interface. The adapter class must have a default constructor and must implement the T parse(String value) and void write(T value, JsonWriter writer) throws IOException methods.

Assume a JSON document that has a date-type field formatted as dd-M-yyyy. The sample JSON schema is below. Assume that the MyDateJSONParser class was added to imports. You may specify the fully-qualified class name instead, i.e. adapter='com.mycompany.MyDateJSONParser'.

Here is the sample EPL:

@JsonSchemaField(name=myDate, adapter=MyDateJSONParser)
create json schema JsonEvent(myDate Date)

A basic JSON document is:

{"myDate" : "22-09-2018"}

The class below is a sample parser and writer for date values:

public class MyDateJSONParser implements JsonFieldAdapterString<Date> {
  public Date parse(String value) {
    try {
      return value == null ? null : new SimpleDateFormat("dd-M-yyyy").parse(value);
    } catch (ParseException e) {
      throw new EPException("Failed to parse: " + e.getMessage(), e);
    }
  }

  public void write(Date value, JsonWriter writer) throws IOException {
    if (value == null) {
      writer.writeLiteral("null");
      return;
    }
    writer.writeString(new SimpleDateFormat("dd-M-yyyy").format(value));
  }
}

Instead of providing event property names and types as part of EPL create json schema, you may specify an application class that provides public fields instead. You must provide the class name in the classname annotation value of the JsonSchema annotation.

Assume there is a predefined person event class that has two fields that hold a string-type name and UUID-type id:

public class PersonEvent {
  public String name;
  public UUID id;
}

This example declares the JSON person event to point to the PersonEvent as the event object (below example assumes the class is part of the imports; Or specify the fully-qualified class name).

@public @buseventtype @JsonSchema(className='PersonEvent') create json schema JSONPersonEvent()

A sample JSON document is:

{
  "name": "Joe",
  "id": "ff362753-b20d-4a9f-9144-93919cb12442"
}

Please also see Section G.5, “JSON Application-Provided Class” for application class support and Section G.4, “JSON Supported Types” for type information.

By specifying an application class, you may not:

The following limitations apply: