www.espertech.comDocumentation

Appendix F. Event Representation: Object-Array (Object[]) Events

This section provides information for using Object-array (Object[]) to represent events.

F.1. Overview

An event can also be represented by an array of objects. Event properties of Object[] events are the array element values.

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

A given Object-array event type can have only a single supertype that must also be an Object-array event type. All properties available on the Object-array supertype is also available on the type itself. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes and their subtypes match that expression.

After your application configures an Object-array event type by providing a type name, the type name can be used when defining further Object-array or Map event types by specifying the type name as a property type or an array property type.

One-to-Many relationships in Object-array event types are represented via arrays. A property in an Object-array event type may be an array of primitive, an array of Java object, an array of Map or an array of Object-array.

The runtime can process Object[] events via the sendEventObjectArray(Object[] array, String eventTypeName) method on the EPEventService interface. Entries in the Object array represent event properties.

The runtime does not validate Object array length or value types. Your application must ensure that Object array values match the declaration of the event type: The type and position of property values must match property names and types in the same exact order and object array length must match the number of properties declared via create schema or configuration.

F.2. Object-Array Properties

Object-array event properties can be of any type. Object-array event properties that are Java application objects or that are of type java.util.Map (or arrays thereof) or that are of type Object-array (or arrays thereof) offer additional power:

In order to use Object[] (object-array) events, the event type name and property names and types, in a well-defined order that must match object-array event properties, must be made known to the compiler via configuration or create schema EPL syntax. Please see examples in Section 5.15, “Declaring an Event Type: Create Schema” and Section 17.4.5, “Events Represented by Object[] (Object-array)”.

The code snippet below defines an Object-array event type, creates an Object-array event and sends the event into the runtime. The sample defines the CarLocUpdateEvent event type via configuration (create schema could have been used instead). 

// Define CarLocUpdateEvent event type (example for configuration API)
String[] propertyNames = {"carId", "direction"};   // order is important
Object[] propertyTypes = {String.class, int.class};  // type order matches name order

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("CarLocUpdateEvent", propertyNames, propertyTypes);

The CarLocUpdateEvent can now be used in a statement: 

select carId from CarLocUpdateEvent(direction = 1)#time(1 min)
// Send an event
Object[] event = {carId, direction};
runtime.getEventService().sendEventObjectArray(event, "CarLocUpdateEvent");

The runtime can also query Java objects as values in an Object[] event via the nested property syntax. Thus Object[] events can be used to aggregate multiple data structures into a single event and query the composite information in a convenient way. The example below demonstrates a Object[] event with a transaction and an account object. 

runtime.getEventService().sendEventObjectArray(new Object[] {txn, account}, "TxnEvent");

An example statement could look as follows: 

select account.id, account.rate * txn.amount 
from TxnEvent#time(60 sec) 
group by account.id

F.3. Object-Array Supertype

Your Object[] (object-array) event type may declare one supertype when configuring the type.

The supertype of a Object[] event type must also be an object-array event type. All property names and types of a supertype are also available on a subtype and override such same-name properties of the subtype. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes also matches that expression (similar to the concept of interface or superclass).

The properties provided by the top-most supertype must occur first in the object array. Subtypes each append to the object array. The number of values appended must match the number of properties declared by the subtype.

For example, assume your application declares the following two types: 

create objectarray schema SuperType (p0 string)
create objectarray schema SubType (p1 string) inherits SuperType

The object array event objects that your application can send into the runtime are shown by the next code snippet: 

runtime.getEventService().sendEventObjectArray(new Object[] {"p0_value", "p1_value"}, "SubType");
runtime.getEventService().sendEventObjectArray(new Object[] {"p0_value"}, "SuperType");

F.4. Advanced Object-Array Property Types

Strongly-typed nested Object[]-within-Object[] events can be used to build rich, type-safe event types on the fly. Use the addEventType method on Configuration or the create schema EPL syntax.

Noteworthy points are:

For demonstration, in this example our top-level event type is an AccountUpdate event, which has an UpdatedFieldType structure as a property. Inside the UpdatedFieldType structure the example defines various fields, as well as a property by name 'history' that holds a JavaBean class UpdateHistory to represent the update history for the account. The code snippet to define the event type is thus: 

String[] propertyNamesUpdField = {"name", "addressLine1", "history"};
Object[] propertyTypesUpdField = {String.class, String.class, UpdateHistory.class};

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("UpdatedFieldType", propertyNamesUpdField, propertyTypesUpdField);

String[] propertyNamesAccountUpdate = {"accountId", "fields"};
Object[] propertyTypesAccountUpdate = {long.class, "UpdatedFieldType"};
configuration.getCommon().addEventType("AccountUpdate", propertyNamesAccountUpdate, propertyTypesAccountUpdate);

The next code snippet populates a sample event and sends the event into the runtime: 

Object[] updatedField = {"Joe Doe", "40 Popular Street", new UpdateHistory()};
Object[] accountUpdate = {10009901, updatedField};

runtime.getEventService().sendEventObjectArray(accountUpdate, "AccountUpdate");

Last, a sample statement to interrogate AccountUpdate events is as follows: 

select accountId, fields.name, fields.addressLine1, fields.history.lastUpdate
from AccountUpdate

To model repeated properties within an Object-array, you may use arrays as properties in an Object-array. You may use an array of primitive types or an array of JavaBean objects or an array of a previously declared Object-array or Map event type.

When using a previously declared Object-array event type as an array property, the literal [] must be appended after the event type name.

This following example defines an Object-array event type by name Sale to hold array properties of the various types. It assumes a SalesPerson Java class exists and an Object-array event type by name OrderItem was declared: 

String[] propertyNames = {"userids", "salesPersons", "items"};
Object[] propertyTypes = {int[].class, SalesPerson[].class, "OrderItem[]");

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("SaleEvent", propertyNames, propertyTypes);

The three properties that the above example declares are:

The next statement is a sample statement asking for property values held by arrays: 

select userids[0], salesPersons[1].name, 
    items[1], items[1].price.amount from SaleEvent