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 event parser/builder found in the ap-util.jar file, which is located in the Apama installation's lib directory 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).

List<String> list = new ArrayList<String>();
list.add("abc");
list.add("de\"f");
Map<String,String> map = new HashMap<String,String>();
map.put("key1", "value1");
map.put("key\"{}2", "value\"{}2");
final SequenceFieldType STRING_SEQUENCE_FIELD_TYPE =
    new SequenceFieldType(StringFieldType.TYPE);
final DictionaryFieldType STRING_DICT_FIELD_TYPE =
    new DictionaryFieldType(StringFieldType.TYPE, StringFieldType.TYPE);
NormalisedEvent event = new NormalisedEvent();
event.add("mySequenceField",
    STRING_SEQUENCE_FIELD_TYPE.format(list));
event.add("myDictionaryField", STRING_DICT_FIELD_TYPE.format(map));

The programming interface for constructing and using normalized events is made up of three Java classes:

NormalisedEvent

The NormalisedEvent class represents a single normalized event. This class the most important part of the interface, and encapsulates the data and operations that can be performed on a single normalized event.

Normalized events are not thread-safe. If your code will be accessing the same normalized event object (or associated iterators) from multiple threads, you must implement your own thread synchronization to prevent concurrent modification.

A public zero-argument constructor is provided for creation of new (initially empty) NormalisedEvent objects.

NormalisedEventIterator

Several of the NormalisedEvent methods return an instance of the NormalisedEventIterator class, which provides a way to step though the name-value pairs making up the normalized event, forwards or backwards.

There is no public constructor. Iterators are created and returned only by NormalisedEvent methods.

NormalisedEventException

Any errors encountered by NormalisedEvent result in instances of NormalisedEventException being thrown.

See the API Reference for Java (Javadoc) for detailed information on these classes.