The JSON codec connectivity plug-in
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).
For example, a JSON document like
{"a":2,"b":["x","y","z"]}
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:
event E {
integer a;
sequence<string> b;
}
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.
There are two identically behaving versions of the JSON codec, one implemented using C++ and the other implemented using Java. The C++ version of the codec has the same behavior as the Java version, but it usually gives a better performance. See
Deploying plug-in libraries for more information.
A Java sample is provided in the samples/connectivity_plugin/java/JSON-Codec directory of your Apama installation. This provides 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 one below is required in the
connectivityPlugins section of the configuration file (see also
Configuration file for connectivity plug-ins). You can then just have a JSON codec in a chain in between the host and a transport. No configuration is required for this plug-in.
Configuration file entry for Java:
jsonCodec:
directory: ${APAMA_HOME}/lib/
classpath:
- json-codec.jar
class: com.softwareag.connectivity.plugins.JSONCodec
Configuration file entry for C++:
jsonCodec:
libraryName: connectivity-json-codec
class: JSONCodec
The following configuration option is available for the JSON codec:
Configuration option | Description |
filterOnContentType | If set to true and the metadata.contentType is set to anything other than "application/json", then the codec will ignore the event in either direction and pass it on unmodified. If set to false, then the codec will attempt to process the message no matter what the value of metadata.contentType is. Default: false. |
filterOnContentType can be used in chains which have multiple messages of different types through the chain with a transport or mapper configuration which is setting the metadata.contentType field in the messages. It allows the JSON codec to only process messages which (hostwards) are correctly encoded in JSON or (transportwards) should be encoded in JSON. Other messages need to be handled by another codec in the chain which will handle non-JSON-encoded messages.
