Predefined connectivity plug-ins

The JSON codec can be used if you have a transport that is dealing with messages in the JSON format and you want your EPL application to be able to interact with it by sending and listening for events. It does not matter whether the transport

takes JSON-formatted data from an external system and sends it towards the host, or

wants to be given JSON-formatted data from the direction of the host, and then sends it to an external system, or

even does both of the above.

The JSON codec does bidirectional translation between JSON documents in the payload of a message (transport side) and an object in the payload of a message (host side). The JSON document will be stored as a string in the message payload, and the corresponding object will be of a type that the apama.eventMap host plug-in can understand (see Host plug-ins and configuration and Map contents used by the apama.eventMap host plug-in for more information on this host plug-in).

on the transport side corresponds to a java.util.Map (Java) or map_t (C++) on the host side. This java.util.Map or map_t maps a string to an integer for one map entry and a string to a list of strings for the other entry. When the apama.eventMap host plug-in sees an object like this, it will be able to map it to/from an EPL event type such as the following:

The above assumes that either the metadata sag.type is set to E (see also Metadata values) or the apama.eventMap host plug-in has been configured with defaultEventType: E. Remember that this is completely bidirectional.

See the samples/connectivity_plugin/java/JSON-Codec directory of your Apama installation for a more detailed end-to-end example of this codec (along with the source code to this codec), which allows an EPL application to consume and emit JSON as EPL events.

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

The Classifier codec can be used to take messages from a transport and assign them message types suitable for the host. Typically this is the type of an EPL event, which corresponds to the metadata field sag.type (see also Metadata values) when you are using the apama.eventMap host plug-in. The classifier can inspect the message payload and metadata in order to classify messages to the correct type. If it finds a match, it sets the sag.type appropriately, overwriting anything which was there before.

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

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

You then need to add classifierCodec into your connectivity chains with the configuration for that instance. An example configuration may look as follows:

classifierCodec:
rules:
- SomeType:
- payload.someField: someValue
- payload.anotherField:
- AnotherType:
- metadata.metadataField: true
- FallbackType:

The top-level configuration element is just rules. It contains a list of one or more types which can be assigned to messages. Each type contains a list of rules to match against the type with the following properties:

Types are evaluated in order and the first one to match is assigned to a message.

If the list of rules for a type is empty, then it matches any message. There should be only one such type and it must be last. With FallbackType in the above example configuration, it is always guaranteed that a type is set on a message (because FallbackType is a last resort).

Rules within a type are evaluated in order, and comparisons stop on the first failure so that common cases are evaluated first.

Rules within a type give the name of a field as the key and either a string value or empty as the value.

Field names must start with "metadata." or "payload.".

Payload field names must not contain a period (.).

Empty rules match if the field is present (even if empty) with any value. With SomeType in the above example configuration, this rule matches if anotherField in the payload contains any value.

All rules within a type must be true to match that type. For the above example configuration, this means that if anotherField in the payload exists, but someField does not contain someValue, then SomeType does not match.

If no types match, then the sag.type metadata field remains unchanged.

For "payload." rules to match, the payload must be a java.util.Map (Java) or map_t (C++) with string keys.

Messages coming from the direction of the host do not interact with the Classifier codec at all. Use the apama.eventMap host plug-in, which always sets a sag.type for messages going from the host towards the transport.

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 plugins 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:
SomeType:
towardsHost:
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.

defaultValue - If a metadata field, payload field or top-level payload is unset, then set it to a constant string 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.

mapFrom rules are always applied before defaultValue rules.

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 (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".

Payload field names must not contain a period (.).

If it is not possible to read a field, then the message is discarded with a warning.

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

Although metadata only contains strings, it is possible to map a non-string payload or payload field into a metadata key. The non-string value is turned into its string representation, if possible.

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.