www.espertech.comDocumentation

Appendix E. Event Representation: java.util.Map Events

This section provides information for using objects that implement the java.util.Map interface to represent events.

For NEsper .NET also see Section I.8, “.NET IDictionary Events”.

Events can also be represented by objects that implement the java.util.Map interface. Event properties of Map events are the values in the map accessible through the get method exposed by the java.util.Map interface.

Similar to the Object-array event type, the Map event type takes part in the comprehensive type system that can eliminate the need to use Java classes as event types, thereby making it easier to change types at runtime or generate type information from another source.

A given Map event type can have one or more supertypes that must also be Map event types. All properties available on any of the Map supertypes are available on the type itself. In addition, anywhere within EPL that an event type name of a Map supertype is used, any of its Map subtypes and their subtypes match that expression.

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

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

The runtime can process java.util.Map events via the sendEventMap(Map map, String eventTypeName) method on the EPEventService interface. Entries in the Map represent event properties. Keys must be of type java.util.String for the compiler to be able to look up event property names specified by statements.

The runtime does not validate Map event property names or values. Your application should ensure that objects passed in as event properties match the create schema property names and types, or the configured event type information when using runtime or static configuration.

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

In order to use Map events, the event type name and property names and types 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.4, “Events Represented by java.util.Map”.

The code snippet below defines a Map event type, creates a Map 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
Map<String, Object> def = new HashMap<String, Object>;
def.put("carId", String.class);
def.put("direction", int.class);

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

The CarLocUpdateEvent can now be used in a statement:

select carId from CarLocUpdateEvent(direction = 1)#time(1 min)
// Create a CarLocUpdateEvent event and send it into the runtime for processing
Map<String, Object> event = new HashMap<String, Object>();
event.put("carId", carId);
event.put("direction", direction);

runtime.getEventService().sendEventMap(event, "CarLocUpdateEvent");

The runtime can also query Java objects as values in a Map event via the nested property syntax. Thus Map 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 Map event with a transaction and an account object.

Map event = new HashMap();
event.put("txn", txn);
event.put("account", account);
runtime.getEventService().sendEventMap(event, "TxnEvent");

An example statement could look as follows.

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

Your Map event type may declare one or more supertypes when configuring the type.

Supertypes of a Map event type must also be Map event types. 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 a Map supertype is used, any of its Map subtypes also matches that expression (similar to the concept of interface in Java).

This example assumes that the BaseUpdate event type has been declared and acts as a supertype to the AccountUpdate event type (both Map event types):

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("AccountUpdate", accountUpdateDef, new String[] {"BaseUpdate"});

Your application statements may select BaseUpdate events and receive both BaseUpdate and AccountUpdate events, as well as any other subtypes of BaseUpdate and their subtypes.

// Receive BaseUpdate and any subtypes including subtypes of subtypes
select * from BaseUpdate

Your application Map event type may have multiple supertypes. The multiple inheritance hierarchy between Maps can be arbitrarily deep, however cyclic dependencies are not allowed. If using configuration, supertypes must exist before a subtype to a supertype can be added.

See Section 17.4.4, “Events Represented by java.util.Map” for more information on configuring Map event types.

Strongly-typed nested Map-within-Map 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:

Map<String, Object> updatedFieldDef = new HashMap<String, Object>();
updatedFieldDef.put("name", String.class);
updatedFieldDef.put("addressLine1", String.class);
updatedFieldDef.put("history", UpdateHistory.class);
Configuration configuration = new Configuration();
configuration.getCommon().addEventType("UpdatedFieldType", updatedFieldDef);

Map<String, Object> accountUpdateDef = new HashMap<String, Object>();
accountUpdateDef.put("accountId", long.class);
accountUpdateDef.put("fields", "UpdatedFieldType");	
// the latter can also be:  accountUpdateDef.put("fields", updatedFieldDef);

configuration.getCommon().addEventType("AccountUpdate", accountUpdateDef);

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

Map<String, Object> updatedField = new HashMap<String, Object>();
updatedField.put("name", "Joe Doe");
updatedField.put("addressLine1", "40 Popular Street");
updatedField.put("history", new UpdateHistory());

Map<String, Object> accountUpdate = new HashMap<String, Object>();
accountUpdate.put("accountId", 10009901);
accountUpdate.put("fields", updatedField);

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

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

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