Working with normalized events
The function of a decoding codec plug-in is to convert incoming messages into a standard normalized event format that can be processed by the Semantic Mapper. Events sent upstream to an encoding codec plug-in are provided to the plug-in in this same format.
Normalized events are essentially dictionaries of name-value pairs, where the names and values are both character strings. Each name-value pair nominally represents the name and content of a single field from an event, but users of the data structure are free to invent custom naming schemes to represent more complex event structures. Names must be unique within a given event. Values may be empty or NULL.
Some examples of normalized event field values for different types are:
string "a string" integer "1" float "2.0" decimal "100.0d" sequence<boolean> "[true,false]" dictionary<float,integer> "{2.3:2,4.3:5}" SomeEvent "SomeEvent(12)" Note: | When assigning names to fields in normalized events, keep in mind that the fields and transport attributes for event mapping conditions and event mapping rules both use a list of fields delimited by spaces or commas. This means, for example that <id fields="Exchange EX,foo" test="==" value="LSE"/> will successfully match a field called "Exchange", "EX" or "foo", but not a field called "Exchange EX,foo". While fields with spaces or commas in their names may be included in a payload dictionary in upstream or downstream directions, they cannot be referenced directly in mapping or id rules. |
To construct strings for the normalized event fields representing container types (dictionaries, sequences, or nested events), use the EventWriter utility found in the AP_EventWriter.h header file, which is located in the include directory of the Apama installation. The following examples show how to add a sequence and a dictionary to a normalized event (note the escape character “ \ “ used in order to insert a quotation mark into a string).
#include <AP_EventWriter.h>
AP_EventWriter *map, *list;
AP_NormalisedEvent *event;
AP_EventWriterValue key, value;
list=AP_EventWriter_ctor(AP_SEQUENCE, NULL);
list->addString(list, "abc");
list->addString(list, "de\"f");
map=AP_EventWriter_ctor(AP_DICTIONARY, NULL);
key.stringValue="key1"; value.stringValue="value";
map->addDictValue(map, AP_STRING, key, AP_STRING, value);
key.stringValue="key\"{}2";
value.stringValue="value\"{}2";
map->addDictValue(map, AP_STRING, key, AP_STRING, value);
event=AP_NormalisedEvent_ctor();
event->functions->addQuick(event, "mySequenceField",
event->functions->list->toString(list));
event->functions->event->functions->addQuick(event,
"myDictionaryField", event->functions->map->toString(map));
AP_EventWriter_dtor(list);
AP_EventWriter_dtor(map);
Fields names and values of normalized events are in UTF-8 format. This means that the writer of the codec needs to ensure that downstream events are correctly formed and the codec should expect to handle UTF-8 coming upstream.
The NormalisedEvent.h header file defines objects and functions that make up a special programming interface for constructing and examining normalized events.
NormalisedEvent.h contains two main structures: AP_NormalisedEvent which represents a single normalized event, and AP_NormalisedEventIterator which can be used to step through the contents of a normalized event structure.