The Mapper codec connectivity plug-in

The Mapper codec can be used to take messages from a transport which do not match the schema expected by the host and turn them into messages which are suitable for the host. Typically this means making sure that the fields in the message have the same names as the fields in the corresponding EPL event type if you are using the apama.eventMap host plug-in. This codec can move fields around between the payload and the metadata and set the values of fields which have no value from the transport. It is bidirectional and can also map messages coming from the host into a format suitable for the transport.

The source code for this plug-in is also shipped as a sample in the samples/connectivity_plugin/cpp/mapper directory of your Apama installation.

To reference the Mapper codec, an entry such as the following is required in the connectivityPlugins section of the configuration file (see also Configuration file for connectivity plug-ins):

You then need to add mapperCodec into your connectivity chains with the configuration for that instance. If you are also using the Classifier codec to assign types to incoming messages, then you must have that codec on the transport side of the Mapper codec. An example configuration may look as follows:

mapperCodec:
allowMissing: true
SomeType:
towardsHost:
copyFrom:
- payload.c: metadata.c
mapFrom:
- payload.a: metadata.a
- payload.b: metadata.b
defaultValue:
- payload.c: A default value
towardsTransport:
mapFrom:
- metadata.a: payload.a
- metadata.b: payload.b
"*":
towardsHost:
defaultValue:
- payload.d: A different value

The configuration of the Mapper codec is a map of type names. Types of messages are identified using the sag.type metadata field (see also Metadata values). A key in the configuration must either be the name of a type, or the special symbol "*" (which must include the quotes so that it can be parsed in the YAML format correctly). Messages are first processed with any rules matching their specific type. After this, the rules under "*" are applied to all messages.

towardsHost - Messages going from the transport to the host.

towardsTransport - Messages going from the host to the transport.

mapFrom - Move the contents of a metadata field, payload field or top-level payload to another metadata field, payload field or top-level payload. For the above example configuration, this means that if a message of type SomeType is being passed from the transport towards the host, then the field a from the metadata is removed and its value is put into the field a of the payload (the same applies for the b case). Note that it is always the field on the right-hand side of the rule which is removed. For example, when a message of type SomeType is going from the host towards the transport, then the resulting message no longer has the payload fields a and b.

copyFrom - This action is exactly the same as the mapFrom action except that the source field is not removed after the copy.

defaultValue - If a metadata field, payload field or top-level payload is unset or empty/null, then set it to a specified value. For the above example configuration, this means that if a message of any type is being passed from the transport towards the host, then the field d of its payload is set to A different value if - and only if - that field does not already exist in the map. The following applies:

The sets of rules are applied in the following order: copyFrom, mapFrom, defaultValue.

Rules are applied in order within each rules section, so you can move the contents out of a field and then replace it with a different value.

Rules within a type give the name of a field on the left-hand side, and the name of a field (copyFrom/mapFrom) or a constant string value (defaultValue) on the right-hand side. The left-hand side is the field whose value is being set.

Field names must start with "metadata." or "payload.", or must be the string "payload".

Metadata and payload field names which contain a period (.) refer to nested map structures within the metadata or payload. For example, metadata.http.headers.accept refers to a map called "http" within the metadata, which contains a map called "headers", which contains an element called "accept".

A copyFrom or mapFrom rule where the source field does not exist uses the default value if the defaultValue exists or if a subsequent copyFrom or mapFrom rule exists for the same destination field. If none of these fallback options exist (like a defaultValue), then the message is discarded with an error.

The boolean allowMissing affects all rules in the Mapper codec. By default, this is set to false. If allowMissing is set to true, an error is not raised when a defaultValue (or a subsequent copyFrom or mapFrom rule) has not been set and a source field is missing. allowMissing needs to be defined at the same level as the event types.

If setting a payload field on a payload that is not a map, the payload is first overwritten with an empty map.

payload in the left-hand side or right-hand side of a rule (rather than payload.fieldname) refers to the entire payload object. This allows you, for example, to map an entire string payload into a field in a map in the resulting message's payload, or vice-versa.